A requirements.txt file lists every Python package your project needs to run

A requirements.txt file is a plain text document that tells Python which packages to install and which versions to use. When you or someone else runs your project on a different computer, Python reads this file and installs exactly the same packages in exactly the same versions. Without it, your code might work on your machine but break on someone else's because they have different package versions installed.

The file lives in your project's root folder — the top level where your main code files sit. Each line names one package. You can add version numbers, comments, or install options. Python's package manager, pip, reads the file and does the installation work for you in one command.

Key Takeaways

  • Create a requirements.txt file by running pip freeze > requirements.txt in your project folder, which captures every package you currently have installed.
  • Edit the file by hand to remove packages you don't actually need and to pin versions you want to keep stable, using the format package-name==1.2.3.
  • Share the file with your project so others can install all dependencies at once using pip install -r requirements.txt.
  • Use version pinning (==) for production code and looser constraints (>=) for libraries others will build on top of, depending on your stability needs.

The fastest way: pip freeze

The simplest method is to let pip tell you what you have. Open your terminal or command prompt, navigate to your project folder, and run:

pip freeze > requirements.txt

This command writes every package you have installed into a new file called requirements.txt. Each line looks like requests==2.31.0 or flask==3.0.0. The double equals sign means "this exact version".

The catch: pip freeze captures everything you have installed in your Python environment, not just what your project uses. If you installed packages for other projects, they all show up. You will need to edit the file afterward to remove the ones that don't belong.

Editing the file to keep only what you need

Open requirements.txt in any text editor. Delete any line for a package your project doesn't actually import. Keep only the packages your code calls import on.

For example, if your project uses Flask and Requests, your file might look like:

Flask==3.0.0 Requests==2.31.0 Werkzeug==3.0.1 click==8.1.7

Flask and Requests are packages you chose. Werkzeug and click are dependencies — packages that Flask needs to run. You can keep them listed (so the versions stay consistent) or remove them and let pip install them automatically when it installs Flask. Either way works; listing them just makes the installation more predictable.

One line per package. No blank lines between them. Save the file.

Version pinning: when to use == versus >=

The double equals sign (==) locks a package to one exact version. Use this for projects you are shipping to users or deploying to a server. It guarantees that everyone runs the same code against the same package behavior.

The greater-than-or-equal sign (>=) allows newer versions. Use this if you are writing a library that others will build on top of. It lets their projects use newer package versions without breaking your library. For example, requests>=2.28.0 means "requests version 2.28.0 or newer".

You can also use ranges: flask>=3.0.0,<4.0.0 means "version 3 but not version 4". This is useful when you know a major version change will break your code but you want to allow bug fixes.

For most projects starting out, use == for everything. It is the safest choice and the easiest to understand.

Installing packages from a requirements.txt file

Once you have created and edited the file, anyone with your project can install all the packages at once:

pip install -r requirements.txt

The -r flag tells pip to read the file. It installs every package listed, in the exact versions you specified. If a package is already installed in a different version, pip uninstalls the old one and installs the new one.

This is much faster than asking someone to run five separate install commands. It also prevents the mistake of forgetting one package and having the code fail halfway through.

Keeping requirements.txt up to date

When you add a new package to your project, install it with pip as usual: pip install new-package-name. Then run pip freeze > requirements.txt again to update the file.

If you are working with others, commit the updated requirements.txt to your version control system (like Git) so they know to run pip install -r requirements.txt again. This is especially important if you upgraded a package to a newer version — they need to know.

Some teams update requirements.txt every time they add a package. Others do it once before shipping. The rule is straightforward: if your code depends on it, it should be in the file.

Using virtual environments with requirements.txt

A virtual environment is a separate Python installation folder for each project. It keeps your project's packages isolated from other projects and from your system Python. This is the standard practice for any project you plan to share or deploy.

Create a virtual environment in your project folder:

python -m venv venv

set up it (the command differs by operating system):

On Mac or Linux: source venv/bin/set up

On Windows: venv\Scripts\set up

Now when you run pip freeze > requirements.txt, you capture only the packages you installed for this project, not everything on your computer. This makes the file much cleaner and more reliable.

Frequently Asked Questions

What if I don't know which packages my project uses?

Run pip freeze > requirements.txt to see everything installed, then look at the import statements in your code files. Keep only the packages you actually import. If you are unsure about a package, search your code for its name — if it does not appear, you probably don't need it.

Can I have multiple requirements.txt files?

Yes. Some projects use requirements-dev.txt for packages only needed during development (like testing tools) and requirements-prod.txt for packages needed in production. You can install both with pip install -r requirements-dev.txt -r requirements-prod.txt, or just the production one when deploying.

What happens if someone installs a package that is not in requirements.txt?

Their code will run, but when someone else clones the project and runs pip install -r requirements.txt, that package will not be installed and the code will break. Always update requirements.txt when you add a package.

Should I commit requirements.txt to Git?

Yes, always. Commit it to your repository so anyone who clones your project knows exactly what to install. Do not commit the venv folder itself — add it to .gitignore instead.

What if two packages need different versions of the same dependency?

This is a dependency conflict. Run pip install package1 package2 and let pip try to find versions that work together. If it cannot, you may need to use an older version of one package, or look for an alternative package that does the same thing.