Using Requirement Files

A Beginner's Guide to pip Austin Cepalia 04:04

A requirements file is a list of all of a project’s dependencies. This includes the dependencies needed by the dependencies. It also contains the specific version of each dependency, specified with a double equals sign (==).

pip freeze will list the current projects dependencies to stdout.

This shell command will export this as a file named requirements.txt:

Shell
      
$ pip freeze > requirements.txt

Once you’ve got your requirements file, you can head over to a different computer or new virtual environment and run the following:

Shell
      
$ pip install -r requirements.txt

That’s assuming you are working in the directory containing requirements.txt. This tells pip to install the specific versions of all the dependencies listed.

By modifying the requirements file to use >= instead of ==, you can tell pip to install the latest stable version of the dependency, with the version specified acting as a minimum. This line would tell pip to install the latest version of requests, but never version 2.23.0: requests>=2.22.0, != 2.23.0.

To upgrade your installed packages, run the following:

Shell
      
$ pip install --upgrade -r requirements.txt

00:00 If you just type the package name when installing with pip, pip will always install the latest published version of that package.

00:08 But sometimes you might want to install a specific version that you know works well with your code. What we really want to do here is create a specification of the dependencies, including the specific versions that we used to develop our application. This way, other developers know exactly what they’ll need to run our program.

00:31 This sounds like a job for a requirements file. A requirements file lists all of a program’s dependencies. As you’ll see in a moment, we can pass this file into pip and it will install all of them for us. Requirements for the current project can be listed to stdout with pip freeze,

00:54 but what we really want to do is redirect that output to a new text file called requirements.txt. This is not a required filename, but it is a convention.

01:08 Now we can quickly view that file with the Unix cat utility, just to make sure everything looks right. You can then head over to a different computer or a new virtual environment and say pip install -r requirements.txt to install every package listed in the file.

01:31 Just make sure your current directory contains this requirements file. You’ll often see this requirements file in public repositories on GitHub. Over time, packages get updated with new performance and security updates. In order to take advantage of them, let’s modify our new requirements file to instruct pip to install the latest and greatest version of these packages.

01:58 I’ll do that with pyvim requirements.txt.

02:04 Notice here that our listed packages all have a specific version specified after a double equal sign (==). This == tells pip that it must install exactly this version of the package.

02:19 We can change these to greater than or equal to signs (>=) if we want to install the newest version. I’ll type i to go into insert mode, and now I can insert the greater than symbol (>) on all of these lines.

02:35 What we’re basically doing is telling pip that this is the minimum required version of the package, but it should use something newer if it’s compatible with the rest of our packages, I’ll hit Escape to exit insert mode and then :wq to save and quit. To tell pip to try and upgrade the current packages with the new requirements, we can say pip install --upgrade -r requirements.txt.

03:11 And as you can see by the output, everything is already up-to-date. Let’s pretend we run our program and we determined that one of the updates to one of our packages breaks everything. We need some way to specify that it should not use that specific version of the package. Let’s head back into the requirements file, and I’ll show you how. By putting a comma (,) after a version number, we can specify more constraints.

03:42 The less than symbol (<) can be used to say that we need a version number less than this version. If we’ve identified just a specific version that doesn’t work, we can also say not equals (!=), like this. As you can see, pip makes it easy to fine-tune packages’ dependencies.

Ivo Houbrechts on Nov. 26, 2023

Hi,

In pyproject.toml, you can specify requires-python = ">=3.8" Is there something similar in requirements files?

Ivo

Become a Member to join the conversation.