Skip to main content

Creating and Managing Requirements Files

A pip requirements file is a list of arguments that pip reads during installation. It is not Python project metadata and, by itself, is not guaranteed to be a complete cross-platform lock file.

Declare project intent​

Create requirements.txt in a text editor and list the direct distributions the project uses:

pandas>=2.2,<3
matplotlib>=3.9,<4

Choose bounds from compatibility evidence and tests, not from arbitrary old examples. An unbounded dependency can admit a breaking release; an unnecessary exact pin can prevent compatible security and bug-fix updates.

Install into a fresh virtual environment:

python -m pip install -r requirements.txt
python -m pip check

Understand pip freeze​

python -m pip freeze > requirements-lock.txt

pip freeze reports installed distributions in a requirements-compatible format. It does not compute a lock from your direct dependencies, explain why a transitive dependency is present, or guarantee the same artifacts on every platform. Run it only in a clean, intentional environment if you use the result as a snapshot.

Maintain requirements safely​

  • Keep requirement and constraint files in version control.
  • Review every dependency update and run the project's tests.
  • Do not store credentials in index URLs committed to the repository.
  • Use hashes or a dedicated lock workflow where artifact integrity and repeatability matter.
  • Periodically create a clean environment and install from the recorded files.

Libraries intended for distribution should declare runtime dependencies in pyproject.toml; requirements files are commonly used to reproduce complete application or development environments.