What a requirements.txt file does and why you need one

A requirements.txt file is a plain text document that lists every Python package your project depends on, along with the version number for each one. When you or someone else runs your project on a different computer, they can install all those packages at once by running a single command, instead of hunting down each package individually.

Without a requirements.txt file, you have to remember which packages you installed, what versions you used, and whether they work together. This becomes a real problem when you share code with teammates, deploy to a server, or come back to a project months later and can't remember what you needed.

The file is simple — just a list of package names, one per line, with optional version numbers. Python's package manager, pip, reads it and installs everything automatically.

Key Takeaways

  • Create a requirements.txt file by running pip freeze > requirements.txt in your project folder, which captures every package currently installed in your Python environment.
  • You can also create the file manually by opening a text editor, typing package names and versions, and saving it as requirements.txt in your project root.
  • Install all packages from a requirements.txt file by running pip install -r requirements.txt in the same directory as the file.
  • Use version pinning (exact versions like requests==2.28.1) for production code, and looser constraints (like requests>=2.28.0) for libraries others will build on.
  • Update your requirements.txt whenever you add or remove packages, so the file stays in sync with what your project actually needs.

The fastest way: using pip freeze

The quickest method is to let pip generate the file for you. Open your terminal or command prompt, navigate to your project folder, and run this command:

pip freeze > requirements.txt

This command captures every package installed in your current Python environment and writes it to a file called requirements.txt. The output looks like this:

requests==2.28.1 numpy==1.23.5 flask==2.2.2 werkzeug==2.2.2

The double equals sign means "this exact version." When someone installs from this file, they get those exact versions, which prevents surprises from package updates that might break your code.

The downside of pip freeze is that it captures every package in your environment, including packages you installed for other projects. If you use a virtual environment (which you should), this is not a problem — the environment only contains what you need for that one project.

Creating a requirements.txt file by hand

You can also write the file yourself. Open any text editor — Notepad, VS Code, or whatever you use — and type the packages your project needs, one per line. Save the file as requirements.txt in your project's root folder (the top-level directory).

A basic requirements.txt looks like this:

requests numpy flask

This tells pip to install the latest version of each package. If you want to pin specific versions, add the version number after two equals signs:

requests==2.28.1 numpy==1.23.5 flask==2.2.2

You can also use other operators for more flexibility. A greater-than sign (>=) means "this version or newer," which is useful if you want to allow bug fixes but not major updates:

requests>=2.28.0 numpy>=1.23.0 flask>=2.2.0

Hand-writing the file takes longer but gives you full control over what goes in it. This is useful when you want to exclude development-only packages or when you are creating a library that others will build on top of.

Installing packages from a requirements.txt file

Once you have a requirements.txt file, installing all the packages is one command. Navigate to the folder containing requirements.txt and run:

pip install -r requirements.txt

The -r flag tells pip to read the file and install everything listed in it. Pip will download and install each package, along with any packages those packages depend on.

If you are working on a team or deploying code to a server, this is how other people get your exact environment set up. They clone your code, run this one command, and they have everything they need.

Keeping your requirements.txt up to date

Your requirements.txt file should match what your project actually uses. When you install a new package with pip install, add it to requirements.txt. When you remove a package, remove it from the file too.

If you are using pip freeze to generate the file, run it again after you make changes to your environment. This overwrites the old file with a fresh list of everything currently installed.

If you are maintaining the file by hand, update it manually each time you add or remove a package. This takes a bit more work but keeps the file clean and focused on what your project actually needs.

A good practice is to regenerate or review your requirements.txt before you share code, deploy to production, or commit to version control. This ensures anyone who uses your code gets the right packages.

Virtual environments and requirements.txt

A virtual environment is a separate Python workspace for each project. It keeps packages for one project from interfering with packages for another project. When you use a virtual environment, pip freeze only captures packages for that one project, which is exactly what you want in requirements.txt.

To create a virtual environment, run this command in your project folder:

python -m venv venv

Then activate it. On Windows, run venv\Scripts\activate. On macOS or Linux, run source venv/bin/activate. After activation, any packages you install go into that environment only.

Once your environment is set up and you have installed the packages your project needs, run pip freeze > requirements.txt. The file will contain only the packages for that project, not your entire system.

Version pinning: when to use exact versions and when to be flexible

Exact versions (like requests==2.28.1) are best for applications you run yourself — websites, scripts, tools. They may provide that your code runs the same way every time, on every computer.

Looser constraints (like requests>=2.28.0) are better for libraries that other developers will use. If you lock your library to one exact version of a dependency, and someone else's code needs a different version, there is a conflict. Allowing a range of versions gives other developers more flexibility.

You can also combine operators. For example, requests>=2.28.0,<3.0.0 means "version 2.28.0 or newer, but not version 3 or higher." This allows bug fixes and minor updates while blocking major changes that might break compatibility.

Frequently Asked Questions

Can I have multiple requirements.txt files for different parts of my project?

Yes. Some projects use requirements.txt for production packages and requirements-dev.txt for development-only packages like testing tools. You can install both by running pip install -r requirements.txt and then pip install -r requirements-dev.txt. Some teams also create separate files for different environments, like requirements-staging.txt and requirements-production.txt.

What if someone installs from my requirements.txt and gets an error?

The most common cause is a version mismatch — a package version that works on your computer does not work on theirs, often because of differences in Python version or operating system. Ask them what error they see and what Python version they are using. You may need to test your requirements.txt on a different setup or relax your version constraints to allow a wider range of compatible versions.

Should I commit requirements.txt to version control?

Yes, always. Commit requirements.txt to Git or whatever version control system you use. This way, anyone who checks out your code can see exactly what packages are needed. Do not commit the virtual environment folder itself — just the requirements.txt file.

How do I remove a package from requirements.txt?

If you created it with pip freeze, uninstall the package with pip uninstall package-name, then run pip freeze > requirements.txt again. If you wrote it by hand, just delete the line from the file. Either way, test that your project still works after removing a package.

Can I use requirements.txt with Python 2?

Technically yes, but Python 2 reached end of life in 2020 and is no longer supported. If you are working with Python 2 code, requirements.txt works the same way, but you should plan to upgrade to Python 3. Most packages no longer support Python 2, so your options will become very limited.