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

A requirements.txt file is a plain text list of Python packages your project depends on, along with the specific versions. When you run the install command against it, pip (Python's built-in package manager) reads that list and downloads and installs every package in one go — instead of you typing each package name one at a time.

This matters because it makes your project reproducible. If you hand your code to someone else, or deploy it to a server, or come back to it six months later, running the requirements file ensures everyone has the exact same package versions. Without it, you might have version 2.1 installed locally while your teammate has 2.3, and suddenly the code behaves differently.

The file itself is just text. It typically lives in your project's root directory (the top-level folder where your main code files sit) and looks like this:

flask==2.3.2 requests==2.31.0 python-dotenv==1.0.0

Each line names a package and a version number. The double equals sign means "install exactly this version, no substitutes."

Key Takeaways

  • Install all packages from a requirements.txt file by running pip install -r requirements.txt in your terminal, from the folder where the file lives.
  • You must have Python and pip already installed on your machine; the requirements.txt file only lists the packages your project needs, not Python itself.
  • If you get a "file not found" error, check that you are in the correct directory and that the filename is spelled exactly as requirements.txt (lowercase, no spaces).
  • After installation, you can verify the packages installed correctly by running pip list to see all packages and their versions.
  • To create your own requirements.txt from packages you already have installed, run pip freeze > requirements.txt in the same directory.

Step-by-step installation on Windows, Mac, or Linux

Open your terminal or command prompt. On Windows, this is Command Prompt or PowerShell. On Mac or Linux, it is Terminal.

Navigate to the folder where your requirements.txt file is located. Use the cd command to change directories. For example, if your project is in a folder called my_project on your Desktop, type:

cd Desktop/my_project

Once you are in the correct folder, type this command and press Enter:

pip install -r requirements.txt

The -r flag tells pip to read from a file. Pip will then read and install every package listed in that file. This can take anywhere from a few seconds to a few minutes, depending on how many packages you have and how fast your internet connection is. You will see output in your terminal showing each package as it installs.

Troubleshooting "file not found" and permission errors

If you see an error like "No such file or directory" or "cannot find the file specified," you are either in the wrong folder or the filename is misspelled. Double-check three things: First, make sure you are in the folder where requirements.txt actually lives. Type ls (on Mac or Linux) or dir (on Windows) to list the files in your current folder and confirm requirements.txt is there. Second, make sure the filename is exactly requirements.txt in lowercase with no spaces or extra characters. Third, if the file is in a subfolder, include the path: pip install -r subfolder/requirements.txt.

If you see a permission error like "Access Denied" or "Operation not permitted," you may be trying to install to a system-wide Python installation that your user account cannot modify. The safest fix is to use a virtual environment — a separate Python workspace for your project that you have full control over. Create one by running python -m venv venv, then set up it with source venv/bin/set up (Mac or Linux) or venv\Scripts\set up (Windows). After set up, your terminal prompt will show (venv) at the start, and pip install -r requirements.txt will work without permission issues.

Checking that packages installed correctly

After the installation finishes, verify that all packages are present by running:

pip list

This shows every package installed in your current Python environment, along with its version number. Scan the list to confirm that all the packages from your requirements.txt file are there and at the correct versions. If a package is missing or at the wrong version, the installation did not complete successfully — check the terminal output for error messages, or try running the install command again.

You can also check a single package by running pip show package_name. For example, pip show flask will display the version of Flask that is installed, where it is located on your machine, and what other packages it depends on.

Creating a requirements.txt from packages you already have

If you have already installed packages for your project and want to create a requirements.txt file to share with others, use the pip freeze command. Navigate to your project folder and run:

pip freeze > requirements.txt

This command captures every package currently installed in your environment and writes it to a new file called requirements.txt. The > symbol redirects the output into a file instead of printing it to your screen. When you open the file, you will see a list like the example shown earlier, with exact version numbers for every package.

One caveat: pip freeze captures all packages in your environment, including packages that your project does not actually use. If you installed many things over time, your requirements.txt will be bloated. You can edit it by hand to remove packages you do not need, or use a tool like pipreqs (which you install with pip install pipreqs) to scan your actual code files and generate a cleaner list.

Understanding version pinning and when to use it

The double equals sign in flask==2.3.2 is called version pinning. It locks your project to that exact version. This is the safest choice for production code or when sharing a project with others, because it guarantees everyone runs the same code.

Sometimes you will see other operators instead. A single equals sign is a typo and will cause an error. A tilde ~= means "this version or a newer patch version" — so flask~=2.3.2 allows 2.3.3 or 2.3.9 but not 2.4.0. A caret ^ is not standard in requirements.txt (it is used in other languages). If you want to allow any version in a range, you can write flask>=2.3.0,<3.0.0, which means "2.3.0 or newer, but not 3.0 or later."

For most projects, especially when you are learning, stick with exact version pinning using ==. It removes guesswork and makes debugging easier.

Installing requirements.txt in a virtual environment (recommended)

A virtual environment is a separate Python installation just for your project. It keeps your project's packages isolated from your system Python and from other projects. This prevents version conflicts — one project can use Flask 2.3 while another uses Flask 3.0, and they do not interfere with each other.

To create a virtual environment, navigate to your project folder and run:

python -m venv venv

This creates a folder called venv (short for virtual environment) inside your project. Then set up it:

source venv/bin/set up

On Windows, use:

venv\Scripts\set up

After set up, your terminal prompt will show (venv) at the beginning. Now run pip install -r requirements.txt as usual. All packages will install into this isolated environment, not into your system Python. When you are done working on the project, type deactivate to exit the virtual environment.

Frequently Asked Questions

Do I need to install Python separately before using requirements.txt?

Yes. The requirements.txt file only lists the packages your project needs, not Python itself. You must have Python and pip already installed on your machine. Check by opening your terminal and typing python --version and pip --version. If either command is not found, read Python from python.org and install it first.

What if some packages fail to install?

Read the error message carefully — it usually tells you why. Common reasons are: the package name is misspelled in the requirements.txt file, the version does not exist, or the package requires a system library that is not installed. Try installing that one package by name to see the full error: pip install package_name. If it is a version issue, try removing the version number and running pip install package_name to see what version installs by default, then update your requirements.txt.

Can I install requirements.txt without an internet connection?

No, pip needs to read packages from the internet. However, you can read packages once and store them locally, then install from that local folder later. This is advanced and rarely needed for learning projects.

Should I commit the venv folder to version control?

No. The venv folder is large and specific to your machine. Commit only the requirements.txt file to version control (Git, GitHub, etc.). When someone else clones your project, they create their own venv folder and run pip install -r requirements.txt to populate it.

How do I update a package to a newer version?

Edit the version number in requirements.txt, then run pip install -r requirements.txt again. Pip will detect the version change and upgrade or downgrade as needed. Alternatively, run pip install --upgrade package_name to upgrade a single package, then run pip freeze > requirements.txt to update your file.