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

A requirements.txt file is a text document that lists every Python package your project needs, along with the version number for each one. When you run the install command against this file, Python downloads and sets up all those packages at once instead of you typing each name individually. This matters because a project might depend on ten or twenty packages, and those packages might depend on other packages — the requirements file handles all of that in one step.

You will encounter requirements.txt files when you read an existing project from GitHub, when a colleague shares their code with you, or when you follow a tutorial that provides one. The file is plain text, so you can open it in any editor and read exactly what gets installed. Each line names one package, and you can see at a glance what your project uses.

Key Takeaways

  • A requirements.txt file lists all the Python packages a project needs, one per line, with optional version numbers.
  • You install from the file using pip install -r requirements.txt in your terminal or command prompt, run from the folder where the file sits.
  • Python must be installed on your computer first, and you should create a virtual environment before installing to keep packages separate from other projects.
  • If installation fails, check that you are in the correct folder, that your Python version matches what the project expects, and that you have internet access.
  • You can create your own requirements.txt file by running pip freeze > requirements.txt after installing packages in a project.

Setting up before you install

Before you run the install command, make sure Python is installed on your computer. Open your terminal (on Mac or Linux) or command prompt (on Windows) and type python --version. If you see a version number, Python is ready. If you see "command not found" or "not recognized", read Python from python.org and run the installer.

Next, open your terminal or command prompt and navigate to the folder where your requirements.txt file is located. On Windows, use cd followed by the folder path — for example, cd C:\Users\YourName\Documents\my-project. On Mac or Linux, use cd with the path to your project folder. Type ls (Mac or Linux) or dir (Windows) to list the files in that folder and confirm you see requirements.txt.

Creating a virtual environment is the step most people skip and then regret. A virtual environment is a separate folder on your computer where Python packages live for just this one project. This prevents packages from one project from conflicting with packages from another. To create one, type python -m venv venv and press Enter. This creates a folder called venv in your project directory.

Now set up the virtual environment. On Windows, type venv\Scripts\set up. On Mac or Linux, type source venv/bin/set up. You will see the name of the environment appear in parentheses at the start of your terminal line — something like (venv) $. This tells you the virtual environment is active and ready to receive packages.

Running the install command

With your virtual environment active and your terminal in the correct folder, type pip install -r requirements.txt and press Enter. The -r flag tells pip to read from a file instead of installing a single package. Pip will read each package listed in the file and install it, along with any other packages those packages depend on.

Installation can take anywhere from a few seconds to several minutes depending on how many packages are in the file and how fast your internet connection is. You will see text scrolling in your terminal showing the progress. When it finishes, you will see a line that says "Successfully installed" followed by a list of package names, or a message saying the requirements are already met if you have installed them before.

If you see an error message, the most common causes are being in the wrong folder, having a typo in the filename, or having a package that does not exist or is not available for your version of Python. Check that you are in the folder where requirements.txt actually sits by typing ls or dir again. Check that the filename is spelled exactly requirements.txt with no capital letters or extra characters.

Understanding what gets installed

When you open a requirements.txt file in a text editor, you will see lines that look like requests==2.28.1 or flask>=2.0.0. The first part is the package name. The second part after the equals signs or comparison operators specifies which version to install. The double equals sign == means install exactly that version. A single equals sign or >= means install that version or any newer one.

Some requirements files list only the package name with no version number at all, like requests on its own line. This tells pip to install the latest available version. This is less common in professional projects because it can cause unexpected changes if a new version of a package comes out with breaking changes, but you will see it in some tutorials and smaller projects.

You do not need to understand every package in the file to install from it. The file is created by the person who wrote the project, and they have already tested that these specific packages work together. Your job is straightforward to install what they listed.

Creating your own requirements.txt file

Once you have installed packages for your own project and want to share it with someone else or move it to another computer, you can create a requirements.txt file from what you have already installed. With your virtual environment active, type pip freeze > requirements.txt. This command lists every package currently installed in your virtual environment and writes it to a new file called requirements.txt in your current folder.

Open the file in a text editor to see what got written. You will see a list of every package and its exact version number. This is the file you would share with a colleague or upload to GitHub so they can install the exact same packages you used.

If the list includes packages you did not actually use — packages that got installed as dependencies of other packages but are not part of your code — you can edit the file and delete those lines. Keep only the packages your code directly imports. This makes the file cleaner and easier to understand later.

Troubleshooting installation problems

If you see an error like "No module named pip", Python is installed but pip is not set up correctly. On Windows, try python -m pip install -r requirements.txt instead. On Mac or Linux, you may need to use pip3 instead of pip if you have both Python 2 and Python 3 installed.

If a specific package fails to install with an error about a missing compiler or build tools, the package contains code written in C or another language that needs to be compiled for your computer. On Windows, read and install Microsoft C++ Build Tools. On Mac, install Xcode Command Line Tools by typing xcode-select --install. On Linux, install build-essential by typing sudo apt-get install build-essential.

If you see a message that a package is not available for your version of Python, check the Python version the project expects. Some packages only work with Python 3.9 or newer, or only with Python 3.11 and below. Look for a README file or documentation in the project folder that states the required Python version. If your version does not match, you may need to install a different version of Python.

If installation succeeds but you still get "module not found" errors when you try to run the project, make sure your virtual environment is active. You should see the environment name in parentheses at the start of your terminal line. If it is not there, set up it again using the command from the setup section above.

What happens after installation

Once installation finishes, the packages are ready to use. If the project includes Python scripts or a web process, you can now run them. The exact command depends on what the project does — you might type python main.py to run a script, or flask run to start a web server, or something else entirely. Check the project's README file for instructions on what to run next.

Keep your virtual environment active while you work on the project. Every time you open a new terminal window to work on this project, you will need to set up the virtual environment again using the same command from the setup section. When you are done working, you can type deactivate to turn off the virtual environment, though this is not required.

Frequently Asked Questions

Can I install from a requirements file without creating a virtual environment?

Technically yes, but you should not. Installing without a virtual environment puts all packages in your system Python folder, which can cause conflicts if different projects need different versions of the same package. A virtual environment takes 30 seconds to create and saves you hours of debugging later.

What if the requirements.txt file has a different name?

Some projects use names like requirements-dev.txt for development packages or Pipfile if they use a different package manager. Check the project's README file to see which file to install from. If you see a file named Pipfile, use pipenv install instead of pip. If you see pyproject.toml, use pip install -e . from the project folder.

How do I know if installation actually worked?

After installation finishes, type pip list to see all installed packages. You should see the packages from your requirements file in the list. You can also try importing a package in Python by typing python to start the Python interpreter, then import packagename. If no error appears, the package is installed correctly.

Can I update packages after installing from requirements.txt?

Yes, but be careful. Type pip install --upgrade packagename to update a single package. If you update multiple packages, test your project thoroughly because newer versions might have breaking changes. If something breaks, you can reinstall from the requirements file to go back to the original versions.

What if I need to add a new package to my project?

Install it normally with pip install packagename. Then update your requirements file by typing pip freeze > requirements.txt again. This overwrites the old file with a new one that includes the package you just added. Commit this updated file to version control so others know about the new dependency.