pip-freeze

List installed Python packages and versions

TLDR

List installed packages

$ pip freeze

List installed packages and write it to the requirements.txt file

$ pip freeze > requirements.txt

List installed packages in a virtual environment, excluding globally installed packages

$ pip freeze [[-l|--local]] > requirements.txt

List installed packages in the user-site

$ pip freeze --user > requirements.txt

List all packages, including pip, distribute, setuptools, and wheel (they are skipped by default)

$ pip freeze --all > requirements.txt

--local
If a virtual environment is active, only display packages installed into that virtual environment. Otherwise, display packages installed in the global site-packages.

--user
Only display packages installed in the user's site-packages directory. This is useful when pip is configured to install packages only for the current user.

--path

    Restrict to packages installed in the specified directory. This allows inspecting specific installation locations outside of the standard site-packages or virtual environments.

--all
    Show all installed packages, including those that are considered "editable" (e.g., installed with pip install -e). By default, editable packages are shown differently.

--exclude
    Exclude specified package(s) from the output. This option can be used multiple times to exclude several packages (e.g., --exclude pip --exclude setuptools).

--exclude-editable
    Exclude editable packages from the output. This is the opposite of --all, useful when you only want non-editable, 'production' dependencies.

--require-virtualenv
    Exit with an error code if not run inside a virtual environment. This enforces best practices by ensuring dependency pinning only occurs within isolated environments.

DESCRIPTION

pip freeze is a fundamental command in the Python ecosystem for managing project dependencies. It serves to output a list of currently installed Python packages along with their exact version numbers. This list is formatted in a way that is directly compatible with pip install -r, making it an indispensable tool for creating requirements.txt files. These files ensure that all developers working on a project, or deployment environments, can install the identical set of dependencies, thus promoting consistency and reproducibility. The command inspects the active Python environment (whether it's a global installation or a virtual environment) and enumerates the packages found there. It's especially crucial for maintaining virtual environments, allowing users to capture the state of their isolated dependencies before sharing or deploying code.

CAVEATS

Environment Specificity:
pip freeze lists packages from the current active Python environment. If you're not in a virtual environment, it will list global packages, which might not be desirable for project-specific dependency management.
Editable Installs:
By default, editable installs (e.g., pip install -e . or pip install -e git+...) are outputted with a special format (e.g., -e git+...#egg=package-name). This differs from standard package==version pinning and requires careful handling if you intend to reproduce the exact setup. Use --all or --exclude-editable to modify this behavior.
No Transitive Dependencies:
pip freeze only lists the directly installed top-level packages. It does not show their dependencies. While pip install -r will automatically resolve and install transitive dependencies, pip freeze won't explicitly list them.
Exact Version Pinning:
The command outputs exact versions (package==X.Y.Z). While this ensures reproducibility, it can sometimes be too restrictive for development, where dependency ranges (package~=X.Y) might be preferred. However, for requirements.txt used in deployment, exact pinning is generally recommended.

COMMON USAGE: REQUIREMENTS.TXT

The most common and recommended use of pip freeze is to generate a requirements.txt file.

pip freeze > requirements.txt

This file can then be used to install the exact same set of packages on another machine or environment:
pip install -r requirements.txt
. This practice is crucial for reproducible builds and collaborative development.

INTERPRETING OUTPUT

The standard output format is PackageName==VersionNumber, e.g., requests==2.28.1. For editable installs, it typically shows -e git+https://...#egg=PackageName. This format is specifically designed for pip install -r.

BEST PRACTICES FOR REQUIREMENTS.TXT

It's generally recommended to use pip freeze within a virtual environment to capture only project-specific dependencies. Avoid running it globally unless you explicitly want to list all system-wide installed packages. Regularly update your requirements.txt file as dependencies change during development.

HISTORY

The pip (Python Package Installer) tool itself emerged as a replacement for easy_install around 2008-2010, aiming for a more robust and user-friendly experience in managing Python packages. The freeze command has been a core and indispensable feature from pip's early days, central to its mission of simplifying dependency management and promoting reproducible builds. Its design allows for straightforward capturing of an environment's state, directly addressing the common challenge of ensuring consistent dependency sets across different development and deployment environments. The command's output format has remained largely consistent over time, solidifying its role as the de-facto standard for requirements.txt files.