If you have browsed any python projects on Github or elsewhere, you have probably noticed a file called requirements.txt This requirements.txt file is used for specifying what python packages are required to run the project you are looking at. Typically the requirements.txt file is located in the root directory of your project.
If you open a requirements.txt file, you will see something that looks similar to this:
pyOpenSSL==0.13.1
pyparsing==2.0.1
python-dateutil==1.5
pytz==2013.7
scipy==0.13.0b1
six==1.4.1
virtualenv==16.3.0
Notice we have a line for each package, then a version number. This is important because as you start developing your python applications, you will develop the application with specific versions of the packages in mind. Later on, the package maintainer might make changes which would break your application. It is too much work to keep track of every downstream package change. Especially if it is a larger project. So you want to keep track of what version of each package you are using to prevent unexpected changes.
Pip Freeze
So far we have discussed at a high level what the requirements.txt is for. But how do we actually use it? We don’t want to manually install and track every package that is installed on our computer. First, let’s look at the pip freeze command. If you run:
pip freeze
You will see an output similar to what we saw in the previous section. This is a complete list of every package installed on your computer, along with the version numbers. You can copy and paste this output into a requirements.txt file, and you now have all of these packages documented.
You should spend a bit of time comparing what packages were listed in the pip freeze command and removing the packages that are not actually used in your project. If you have done a lot of projects on your computer, you are going to have a lot of packages listed at this point.
pip install
You are probably familiar with the pip install command already. You run pip install <package name> and it will install that package. Further, you can run pip install <package name>==<version number> to install a specific version of a package.
However, instead of installing the packages you need one by one, you should use your requirements.txt file to install the packages. This has two benefits:
- You don’t have to manually type pip install 10 times to get all of your packages installed
- You don’t have to worry about getting the right version installed
By default, pip will just install the latest version of each package. But this might not be the behavior you want. Requirements.txt will install the specific versions you requested.
To install your packages using requirements.txt, it is super easy.
- Open a terminal or command prompt
- Navigate to the folder with your requirements.txt
- run: pip install -r requirements.txt
- You are done installing dependencies
Virtual Environments
Virtual Environments are, what I think, what really makes your requirements.txt powerful. Remember in the first section how we ran pip freeze and it listed all the packages on the entire system? Wouldn’t it be better if it only listed that packages that we care about?
This is one of the benefits of using virtual environments. When you are using a virtual environment, you only see the packages that you have installed in that environment. This helps prevent version conflicts between different projects. It also makes it easier to keep track of your packages.
If you are using a virtual environment, and you want to create your requirements.txt, it is as simple as running this command:
pip freeze > requirements.txt
The command above will list all of the installed packages, and output them to the requirements.txt file.
For more information about how to set up and use virtual environments. see our python virtual environments article here.
Summary
As you have seen, the requirements.txt file is a really useful tool when doing python development. If you do things right, it is very little work to maintain and saves you a lot of time with maintaining package dependencies in your project.
