Understanding requirements.txt

requirements.txt lists the Python packages your application needs. Without precise versions, two installs on two different dates can produce different environments, and a deploy that worked yesterday fails today. The file is short, but its syntax and pinning strategy deserve attention.

Syntax

Flask==3.0.3
requests==2.32.3
gunicorn==22.0.0
uvicorn[standard]==0.30.6

• == pins an exact version.
• ~= accepts compatible patch releases (~=3.0.2).
• A bare >= lets a future major in: avoid it in production.
• [standard] installs optional dependencies.
• ; python_version < "3.12" makes installation conditional on the interpreter.

One package per line, no trailing comma. Comments start with #. Direct URLs and Git repositories work but make reproducibility and audit harder.

Install and reproduce

python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
pip check

pip check reports incompatible dependencies. To capture the full tree after installation:

pip freeze > requirements.txt

pip freeze includes transitive dependencies, which suits a deployed application. For a library, prefer a constraints file or pip-tools, which separates intent (requirements.in) from resolved versions.

On app hosting, the platform installs dependencies before startup. A failure shows in the console: missing version, package requiring compilation, or incompatibility with the selected Python (3.12, 3.11, 3.10, 3.9).

Update without breaking

1. Update one package at a time.
2. Read the changelog, especially for a major release.
3. Recreate a clean environment and reinstall from the file.
4. Test the application, not just an import.
5. Commit the file and note why it changed.

A yanked release can break a reinstall while the app still runs. Keep a copy of the wheels if the project is critical, or pin an available, tested version.

Best practices

• Separate requirements.txt (runtime) from requirements-dev.txt (tests, formatting).
• Do not commit .venv.
• Never put a token in a private repository URL: use an environment variable or an uncommitted config file.
• Keep the file sorted so diffs stay readable.

Check

After installation, start the app and verify the loaded version:

python -c "import flask; print(flask.__version__)"

Then test a route or command that uses the package. If the install passes but the app fails, the cause is often a native dependency built for another Python version, not the file itself.