Using requirements.txt to Declare Dependencies

When you start building Python projects, you'll quickly find yourself relying on external packages—code written by others that saves you from reinventing the wheel. The challenge is keeping track of which packages your project needs and ensuring everyone working on it uses the same versions. This is where requirements.txt comes in. It's a simple text file that acts as a manifest for your project's dependencies, making your work reproducible and portable.

🧠 What is a requirements.txt File?

A requirements.txt file is a plain text file that lists every external Python package your project depends on, along with their specific version numbers. Think of it as a shopping list for your Python environment. When you share your project with a colleague or deploy it to a server, this file tells them exactly what packages to install.

• It lives in the root directory of your project.
• Each line contains one package name, optionally with a version constraint.
• It ensures consistency across different machines and environments.

⚙️ Why Use requirements.txt?

Without a requirements file, you'd have to manually remember and communicate every package your project uses. That quickly becomes impossible as projects grow. Here's why this file is essential:

• Reproducibility – Anyone can recreate your exact environment with a single command.
• Collaboration – Team members get the same versions, avoiding "it works on my machine" problems.
• Deployment – Servers and CI/CD pipelines can install dependencies automatically.
• Documentation – The file itself serves as a clear record of your project's dependencies.

🛠️ How to Create a requirements.txt File

Creating a requirements file is straightforward. You have two main approaches:

Approach 1: Manual Creation - Open a new text file in your project root. - List each package on its own line. - Add version constraints using operators like == (exact version), >= (minimum version), or ~= (compatible release). - Save the file as requirements.txt.

Approach 2: Automatic Generation - After installing packages into your virtual environment, use a tool to scan your environment and generate the file automatically. - This method captures every installed package, including dependencies of your dependencies.

📊 Understanding Version Constraints

Version constraints give you control over which versions of a package are acceptable. Here's a quick comparison of the most common operators:

🕵️ Best Practices for requirements.txt

Follow these guidelines to keep your dependencies clean and manageable:

• Pin exact versions for production projects to avoid unexpected breaking changes.
• Use ranges for libraries where you want flexibility with minor updates.
• Group dependencies logically by adding comments with # symbols to separate development vs. production packages.
• Update regularly to keep dependencies secure and up-to-date.
• Include only top-level dependencies when possible—let pip handle the sub-dependencies automatically.

🔄 How to Use requirements.txt

Once your file is ready, using it is simple. The process works in two directions:

Installing from requirements.txt - When you or someone else clones your project, they create a fresh virtual environment. - They then use the requirements file to install every dependency listed. - The result is an exact replica of your development environment.

Updating requirements.txt - After adding a new package to your project, update the requirements file to include it. - If you upgrade a package, reflect the new version in the file. - Run a check periodically to ensure the file matches your actual environment.

🧪 Common requirements.txt Example

A typical requirements file might look like this when written out:

• flask==2.3.3 – The web framework pinned to an exact version.
• requests>=2.28.0 – HTTP library with a minimum version requirement.
• pandas~=1.5.0 – Data analysis library using compatible release.
• python-dotenv==1.0.0 – Environment variable loader pinned exactly.
• gunicorn==20.1.0 – Production web server pinned exactly.

⚠️ Common Pitfalls to Avoid

Watch out for these mistakes when working with requirements.txt:

• Forgetting to update the file after installing new packages.
• Using overly broad constraints like >= without an upper bound, which can lead to unexpected upgrades.
• Including system-specific packages that won't work on other platforms.
• Mixing development and production dependencies without clear separation.
• Committing the file without verifying it matches your actual environment.

🎯 Key Takeaways

• requirements.txt is your project's dependency manifest, ensuring reproducibility across environments.
• Version constraints give you control over which package versions are installed.
• Pin exact versions for stability, use ranges for flexibility.
• Always keep the file updated and in sync with your actual environment.
• This simple file is one of the most powerful tools for managing Python projects effectively.

By mastering requirements.txt, you ensure that your Python projects are portable, predictable, and professional—ready to be shared, deployed, and maintained with confidence.

A requirements.txt file lists all external packages your Python project needs so other engineers can install them with one command.

📄 Example 1: Creating a simple requirements.txt with one package

This shows the most basic requirements.txt file — a single package name with no version.

# Contents of requirements.txt:
requests

📤 Output: When another engineer runs pip install -r requirements.txt, pip installs the latest version of requests.

📄 Example 2: Pinning a specific version

This shows how to lock a package to a specific version so all engineers use the same code.

# Contents of requirements.txt:
flask==2.3.3

📤 Output: When another engineer runs pip install -r requirements.txt, pip installs flask version 2.3.3 exactly.

📄 Example 3: Using minimum version and version range

This shows how to set a minimum version or a range of acceptable versions.

# Contents of requirements.txt:
numpy>=1.24.0
pandas>=1.5.0,<2.0.0

📤 Output: pip installs numpy version 1.24.0 or newer, and pandas between 1.5.0 and 1.9.9.

📄 Example 4: Multiple packages with different version rules

This shows a realistic requirements.txt with several packages and mixed version constraints.

# Contents of requirements.txt:
requests==2.31.0
flask>=2.3.0
pytest>=7.0.0,<8.0.0
python-dotenv==1.0.0
gunicorn>=20.1.0

📤 Output: pip installs all five packages with their specified version rules in one command.

📄 Example 5: Including development-only dependencies

This shows how to separate main dependencies from tools only needed during development.

# Contents of requirements.txt:
flask==2.3.3
requests==2.31.0
python-dotenv==1.0.0

# Contents of requirements-dev.txt:
pytest==7.4.0
black==23.7.0
flake8==6.1.0

📤 Output: Engineers run pip install -r requirements.txt for production, and pip install -r requirements-dev.txt for development tools.

📄 Example 6: Installing from requirements.txt with a virtual environment

This shows the complete workflow — create a virtual environment, then install all dependencies.

# Step 1: Create virtual environment
python -m venv venv

# Step 2: Activate it (Windows)
venv\Scripts\activate

# Step 2: Activate it (Mac/Linux)
source venv/bin/activate

# Step 3: Install all dependencies from requirements.txt
pip install -r requirements.txt

📤 Output: All packages listed in requirements.txt are installed inside the virtual environment, isolated from the system Python.

📄 Example 7: Freezing current environment into requirements.txt

This shows how to generate a requirements.txt from an already-working environment.

# After installing packages manually, freeze the exact versions
pip freeze > requirements.txt

# Example contents of the generated file:
certifi==2023.7.22
charset-normalizer==3.2.0
click==8.1.6
flask==2.3.3
idna==3.4
itsdangerous==2.1.2
jinja2==3.1.2
markupsafe==2.1.3
requests==2.31.0
urllib3==2.0.4
werkzeug==2.3.6

📤 Output: A complete requirements.txt with exact versions of every package and sub-dependency currently installed.

Comparison Table

When you start building Python projects, you'll quickly find yourself relying on external packages—code written by others that saves you from reinventing the wheel. The challenge is keeping track of which packages your project needs and ensuring everyone working on it uses the same versions. This is where requirements.txt comes in. It's a simple text file that acts as a manifest for your project's dependencies, making your work reproducible and portable.

🧠 What is a requirements.txt File?

A requirements.txt file is a plain text file that lists every external Python package your project depends on, along with their specific version numbers. Think of it as a shopping list for your Python environment. When you share your project with a colleague or deploy it to a server, this file tells them exactly what packages to install.

• It lives in the root directory of your project.
• Each line contains one package name, optionally with a version constraint.
• It ensures consistency across different machines and environments.

⚙️ Why Use requirements.txt?

Without a requirements file, you'd have to manually remember and communicate every package your project uses. That quickly becomes impossible as projects grow. Here's why this file is essential:

• Reproducibility – Anyone can recreate your exact environment with a single command.
• Collaboration – Team members get the same versions, avoiding "it works on my machine" problems.
• Deployment – Servers and CI/CD pipelines can install dependencies automatically.
• Documentation – The file itself serves as a clear record of your project's dependencies.

🛠️ How to Create a requirements.txt File

Creating a requirements file is straightforward. You have two main approaches:

Approach 1: Manual Creation - Open a new text file in your project root. - List each package on its own line. - Add version constraints using operators like == (exact version), >= (minimum version), or ~= (compatible release). - Save the file as requirements.txt.

Approach 2: Automatic Generation - After installing packages into your virtual environment, use a tool to scan your environment and generate the file automatically. - This method captures every installed package, including dependencies of your dependencies.

📊 Understanding Version Constraints

Version constraints give you control over which versions of a package are acceptable. Here's a quick comparison of the most common operators:

🕵️ Best Practices for requirements.txt

Follow these guidelines to keep your dependencies clean and manageable:

• Pin exact versions for production projects to avoid unexpected breaking changes.
• Use ranges for libraries where you want flexibility with minor updates.
• Group dependencies logically by adding comments with # symbols to separate development vs. production packages.
• Update regularly to keep dependencies secure and up-to-date.
• Include only top-level dependencies when possible—let pip handle the sub-dependencies automatically.

🔄 How to Use requirements.txt

Once your file is ready, using it is simple. The process works in two directions:

Installing from requirements.txt - When you or someone else clones your project, they create a fresh virtual environment. - They then use the requirements file to install every dependency listed. - The result is an exact replica of your development environment.

Updating requirements.txt - After adding a new package to your project, update the requirements file to include it. - If you upgrade a package, reflect the new version in the file. - Run a check periodically to ensure the file matches your actual environment.

🧪 Common requirements.txt Example

A typical requirements file might look like this when written out:

• flask==2.3.3 – The web framework pinned to an exact version.
• requests>=2.28.0 – HTTP library with a minimum version requirement.
• pandas~=1.5.0 – Data analysis library using compatible release.
• python-dotenv==1.0.0 – Environment variable loader pinned exactly.
• gunicorn==20.1.0 – Production web server pinned exactly.

⚠️ Common Pitfalls to Avoid

Watch out for these mistakes when working with requirements.txt:

• Forgetting to update the file after installing new packages.
• Using overly broad constraints like >= without an upper bound, which can lead to unexpected upgrades.
• Including system-specific packages that won't work on other platforms.
• Mixing development and production dependencies without clear separation.
• Committing the file without verifying it matches your actual environment.

🎯 Key Takeaways

• requirements.txt is your project's dependency manifest, ensuring reproducibility across environments.
• Version constraints give you control over which package versions are installed.
• Pin exact versions for stability, use ranges for flexibility.
• Always keep the file updated and in sync with your actual environment.
• This simple file is one of the most powerful tools for managing Python projects effectively.

By mastering requirements.txt, you ensure that your Python projects are portable, predictable, and professional—ready to be shared, deployed, and maintained with confidence.

A requirements.txt file lists all external packages your Python project needs so other engineers can install them with one command.

📄 Example 1: Creating a simple requirements.txt with one package

This shows the most basic requirements.txt file — a single package name with no version.

# Contents of requirements.txt:
requests

📤 Output: When another engineer runs pip install -r requirements.txt, pip installs the latest version of requests.

📄 Example 2: Pinning a specific version

This shows how to lock a package to a specific version so all engineers use the same code.

# Contents of requirements.txt:
flask==2.3.3

📤 Output: When another engineer runs pip install -r requirements.txt, pip installs flask version 2.3.3 exactly.

📄 Example 3: Using minimum version and version range

This shows how to set a minimum version or a range of acceptable versions.

# Contents of requirements.txt:
numpy>=1.24.0
pandas>=1.5.0,<2.0.0

📤 Output: pip installs numpy version 1.24.0 or newer, and pandas between 1.5.0 and 1.9.9.

📄 Example 4: Multiple packages with different version rules

This shows a realistic requirements.txt with several packages and mixed version constraints.

# Contents of requirements.txt:
requests==2.31.0
flask>=2.3.0
pytest>=7.0.0,<8.0.0
python-dotenv==1.0.0
gunicorn>=20.1.0

📤 Output: pip installs all five packages with their specified version rules in one command.

📄 Example 5: Including development-only dependencies

This shows how to separate main dependencies from tools only needed during development.

# Contents of requirements.txt:
flask==2.3.3
requests==2.31.0
python-dotenv==1.0.0

# Contents of requirements-dev.txt:
pytest==7.4.0
black==23.7.0
flake8==6.1.0

📤 Output: Engineers run pip install -r requirements.txt for production, and pip install -r requirements-dev.txt for development tools.

📄 Example 6: Installing from requirements.txt with a virtual environment

This shows the complete workflow — create a virtual environment, then install all dependencies.

# Step 1: Create virtual environment
python -m venv venv

# Step 2: Activate it (Windows)
venv\Scripts\activate

# Step 2: Activate it (Mac/Linux)
source venv/bin/activate

# Step 3: Install all dependencies from requirements.txt
pip install -r requirements.txt

📤 Output: All packages listed in requirements.txt are installed inside the virtual environment, isolated from the system Python.

📄 Example 7: Freezing current environment into requirements.txt

This shows how to generate a requirements.txt from an already-working environment.

# After installing packages manually, freeze the exact versions
pip freeze > requirements.txt

# Example contents of the generated file:
certifi==2023.7.22
charset-normalizer==3.2.0
click==8.1.6
flask==2.3.3
idna==3.4
itsdangerous==2.1.2
jinja2==3.1.2
markupsafe==2.1.3
requests==2.31.0
urllib3==2.0.4
werkzeug==2.3.6

📤 Output: A complete requirements.txt with exact versions of every package and sub-dependency currently installed.

Comparison Table