Of course! This is a fundamental concept in Python development. "Python requirements" refers to the specific list of third-party libraries and their versions that your project depends on.

Managing these requirements is crucial for ensuring that your project is reproducible, shareable, and deployable.

Here’s a complete guide covering everything you need to know.

The Core Concept: requirements.txt

The standard way to define a project's dependencies is in a file named requirements.txt. This file is a simple text file where each line specifies a package and its version.

Example requirements.txt file:

requests==2.28.1
pandas>=1.5.0
numpy

What the symbols mean:

• requests==2.28.1: Exact Version. The code must use version 28.1 of the requests library. This is the most precise and safest option for production.
• pandas>=1.5.0: Minimum Version. The code must use version 5.0 or any newer version (e.g., 5.1, 0.0). This allows for bug fixes and improvements but can introduce breaking changes if a major version is updated.
• numpy: Any Version. This is not recommended for production. It will install the latest available version of numpy, which can lead to unexpected behavior if the version changes.

Essential Tools

You'll need two main tools to work with requirements:

1. pip: Python's package installer. It's included with most Python installations. You use pip to install packages from your requirements.txt file.
2. venv: A built-in Python module for creating lightweight, isolated Python environments. This is a critical best practice. You should always work inside a virtual environment to avoid conflicts between project dependencies.

Step-by-Step Workflow

Here is the standard workflow for managing dependencies.

Step 1: Create a Virtual Environment

Navigate to your project's root directory in the terminal and run:

# For Python 3
python -m venv venv
# For macOS/Linux, you might also use:
# python3 -m venv venv

This creates a new directory named venv containing a separate Python installation and packages directory.

Step 2: Activate the Virtual Environment

Before you can install packages into the environment, you need to activate it.

• On macOS/Linux:

  source venv/bin/activate

• On Windows (Command Prompt):

  venv\Scripts\activate

• On Windows (PowerShell):

  .\venv\Scripts\Activate.ps1

You'll know it's active because your command prompt will be prefixed with (venv).

Step 3: Install Packages Manually (Initial Setup)

As you develop your project, you'll install packages one by one using pip.

# Install a specific version
pip install requests==2.28.1
# Install another package
pip install pandas
# Install a package with a minimum version
pip install "numpy>=1.20.0"

Step 4: Generate the requirements.txt File

Once you have all the necessary packages installed in your active virtual environment, you can automatically generate the requirements.txt file.

pip freeze > requirements.txt

• pip freeze lists all the installed packages and their exact versions.
• > redirects this list into a new file named requirements.txt.

Your requirements.txt file will now look something like this:

certifi==2025.9.24
charset-normalizer==2.1.1
idna==3.4
numpy==1.23.5
pandas==1.5.1
requests==2.28.1
urllib3==1.26.12

This file now perfectly captures the state of your project's dependencies.

Step 5: Install Dependencies from the File

Now you can share your project. Anyone else (or you, on a different machine) can set up the project environment by following these steps:

1. Create and activate a new virtual environment (as in Step 1 & 2).

2. Run the following command:

   pip install -r requirements.txt

   • The -r flag tells pip to read the requirements from the specified file (requirements.txt).
   • pip will then install all the listed packages with their exact versions.

Advanced and Best Practices

A. Pinning Dependencies with Hashes (Security)

For maximum security and reproducibility, especially in CI/CD pipelines, you can add hashes to your requirements. This ensures that the package you're installing is the exact same one you tested, preventing malicious package tampering.

You can generate a "hashed" requirements file with:

pip install pip-tools
pip-compile requirements.in

This creates a requirements.txt file with hashes:

#
# This file is autogenerated by pip-compile with Python 3.10
# To update, run:
#
#    pip-compile requirements.in
#
certifi==2025.9.24 \
    --hash=sha256:0cd9a21e5c1f1e6837be0b405789a768b42692a1a1f7d2a3e585940987fb959 \
    --hash=sha256:719a765a6499121a0ec950f081b9512fadc3a3268252bf9573eb924bc5b84fc9 \
    --hash=sha256:90c1a32f1d68f940488354e36370f6b55889145f0ce2b3e3a3f109848d87659c \
    --hash=sha256:9a12422c9a5d9e2754383bc840091f9ce889d3e2485c523b389a455a0f7c7669 \
    --hash=sha256:aa3f8515ecbe5ba6ddd8e47d7aa89f4dc22e0c1b79d2a5a3aa6a703c31a543d8 \
    --hash=sha256:bb7c009a5d68ce64b3b96d8985c6feda6a6a518570d6380488cde90fa839fdd5 \
    --hash=sha256:dd18f963585197fc8d75f237549711d754b61c433b066670c3488973a0485dc8
...

B. Development vs. Production Dependencies

Your project has two types of dependencies:

1. Production Dependencies: Required to run the application (e.g., Flask, Django, SQLAlchemy).
2. Development Dependencies: Required only for development and testing (e.g., pytest, black, flake8, mypy).

It's a best practice to separate these into two files:

• requirements.txt: For production dependencies.
• requirements-dev.txt: For development dependencies.

requirements-dev.txt would look like this:

# Linters and Formatters
black==22.10.0
flake8==5.0.4
# Testing
pytest==7.2.0
pytest-cov==4.0.0
# Development server
pyramid==2.0

You can install development dependencies with:

pip install -r requirements-dev.txt

C. Using pyproject.toml (The Modern Standard)

The Python community is moving away from requirements.txt and setup.py in favor of a single, standardized configuration file: **pyproject.toml``. This file is used by modern build tools likepoetryandpip`.

While requirements.txt is still extremely common, pyproject.toml is the future. Here's an example of how dependencies are defined in it:

[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"
[project]
name = "my-awesome-project"
version = "0.1.0"
description = "A short description of my project."
dependencies = [
    "requests==2.28.1",
    "pandas>=1.5.0",
]
[project.optional-dependencies]
dev = [
    "black",
    "pytest",
]

Summary