If you are working with Python projects, you will often see a file called requirements.txt. This simple text file makes it easy to install all the required Python libraries for a project with just one command.
In this guide, we will explain what requirements.txt is, how to use pip install -r requirements.txt correctly, and how to fix common errors.
What is requirements.txt?
In Python, requirements.txt is a plain text file that contains a list of all the packages (and versions) needed for a project.
Example contents of a requirements.txt file:
requests==2.32.3
pandas==2.2.2
numpy>=1.26.0
flaskEach line represents one package. Some lines also include version numbers so that everyone using the project installs the same versions.
Prerequisites
Before using pip install -r requirements.txt, make sure you have:
- Python installed
- You can check with:
python --versionorpython3 --version
- You can check with:
- pip installed
- Check with:
pip --versionorpython -m pip --version
- Check with:
- requirements.txt file available
- This file is usually in the project’s root folder.
Basic Command: Install from requirements.txt
The most important command is:
pip install -r requirements.txtMany beginners make the mistake of running:
pip install requirements.txtThis is wrong because pip will think requirements.txt is a package name.
The -r flag tells pip to read from a file.
Step-by-Step: How to Use pip install -r requirements.txt
Step 1: Open Command Prompt or Terminal
Depending on your OS:
- Windows:
- Press
Win + R, typecmd, and press Enter. - Or open PowerShell.
- Press
- macOS / Linux:
- Open Terminal from Applications or your launcher.
Step 2: Navigate to Your Project Folder
Use the cd command to move to the folder where requirements.txt is stored.
Example:
cd path/to/your/projectOn Windows, it might look like:
cd C:\Users\YourName\Documents\my-python-projectOn macOS / Linux:
cd /home/yourname/my-python-projectYou can check if the file exists with:
dir # on Windows
ls # on macOS / LinuxLook for requirements.txt in the list.
Step 3: Run the Installation Command
Once you are inside the project directory, run:
pip install -r requirements.txtIf you are using Python 3 and pip is not mapped correctly, you can use:
python -m pip install -r requirements.txtor on some systems:
python3 -m pip install -r requirements.txtpip will now:
- Read each line of the file.
- Download the correct packages from PyPI.
- Install them into your current Python environment.
Using a Virtual Environment (Recommended)
For projects, it is good practice to use a virtual environment so that your dependencies are isolated.
Step 1: Create a Virtual Environment
python -m venv venvThis will create a folder named venv.
Step 2: Activate the Virtual Environment
- Windows (Command Prompt / PowerShell):
venv\Scripts\activate - macOS / Linux:
source venv/bin/activate
You should now see (venv) at the beginning of your terminal prompt.
Step 3: Install from requirements.txt Inside the venv
Now run:
pip install -r requirements.txtAll packages will be installed inside the virtual environment only, not system-wide.
How to Create or Update requirements.txt
If you already installed packages manually using pip install package-name, you can generate a requirements.txt file for your project.
Generate requirements.txt from Current Environment
pip freeze > requirements.txtThis command:
- Lists all installed packages with exact versions.
- Saves them into
requirements.txt.
Manually Editing requirements.txt
You can also open the file in any text editor and add lines such as:
django==5.1.1
psycopg2>=2.9Each package should be on a separate line.
How to Upgrade Packages from requirements.txt
If you want to make sure all packages are installed or upgraded to the versions mentioned in the file, you can use:
pip install --upgrade -r requirements.txtThis will:
- Install missing packages.
- Upgrade existing ones to match the versions in the file.
Common Errors and How to Fix Them
Here are some frequent issues when using pip install -r requirements.txt and how to solve them.
1. ERROR: Could not open requirements file
Example message:
ERROR: Could not open requirements file: [Errno 2] No such file or directory: 'requirements.txt'Cause: You are not in the correct folder, or the file name is different.
Fix:
- Confirm the file exists:
dir # Windows ls # macOS / Linux - Check the spelling: is it
requirements.txtor something likerequirement.txtorrequirements-dev.txt? - If it has a different name, run:
pip install -r my_requirements.txt
2. 'pip' is not recognized as an internal or external command (Windows)
Example message:
'pip' is not recognized as an internal or external command,
operable program or batch file.Cause: pip is not in your system PATH, or Python installation was incomplete.
Fix:
- Try:
python -m pip install -r requirements.txt - If this works, use the
python -m pipstyle for all commands. - If it still fails, reinstall Python from the official website and enable:
- “Add Python to PATH” during installation.
3. Permission Errors (Permission denied / Access is denied)
If you see errors related to permissions:
Fix options:
- Use a virtual environment and install there (recommended).
- Or, on Linux/macOS, use:
pip install --user -r requirements.txtThis installs packages for the current user only.
Avoid using sudo pip install unless you know what you’re doing, as it can affect system-level Python.
4. Package Version Conflicts
Sometimes pip may show warnings about version conflicts, for example:
Requirement already satisfied, but version X is installed which is incompatible with YFix:
- Decide which package/version you really need.
- Update your
requirements.txtwith compatible versions. - Then reinstall:
pip install --upgrade -r requirements.txt
Read More:
