Add --only-explicit Flag to pip freeze to Include Only Explicit Dependencies

[hasanatkazmi]

What's the problem this feature will solve?

Currently, when using pip freeze -r requirements.txt, the output lists all installed packages, including transitive dependencies. This can clutter the requirements file and make it difficult to maintain or audit, as it includes dependencies that were not explicitly declared by the developer. The current behavior can lead to confusion, unnecessary version locking, and potentially more conflicts when managing dependencies. [example]

Describe the solution you'd like

I am trying to create or maintain a requirements.txt file that only includes the top-level dependencies explicitly declared in the original requirements.txt without any transitive dependencies. This would simplify dependency management, making the file more readable and easier to maintain. Currently, there is no straightforward way in pip to generate this type of output.

I would like to see the addition of a --only-explicit flag to pip freeze. When used with the -r option (e.g., pip freeze -r requirements.txt --only-explicit), this flag would ensure that the output includes only the dependencies explicitly listed in the specified requirements file. This would allow developers to keep their requirements.txt clean and focused on the top-level dependencies they are directly responsible for.

Alternative Solutions

Currently, developers may need to manually curate their requirements.txt to remove transitive dependencies or use external scripts to parse and filter the output of pip freeze. Some developers avoid pip freeze altogether for maintaining requirements.txt due to this issue, which reduces the effectiveness of built-in tools and leads to fragmented workflows.

Additional context

https://medium.com/@tomagee/pip-freeze-requirements-txt-considered-harmful-f0bce66cf895

Code of Conduct

• I agree to follow the PSF Code of Conduct.

[pfmoore]

The information that a package was explicitly requested is not currently recorded in the installation metadata. Before pip could implement something like this, it would need to be standardised as part of that metadata. To do that would need a PEP - if you're interested in proposing and writing such a PEP, feel free to bring the issue up on the Packaging Discourse.

[notatallshaw]

The general approach to the problem you are describing and the problem the (quite old) blog post you link is to have two files, typically a requirements.in that describes your actual user needed requirements, and a requirements.txt which is a frozen environment that is a solution to the requirements.in at a given moment in time

You can either write your own workflow that manages environments and uses pip freeze to generate this file, or you can use tools that help solve this workflow for you like pip-tools: https://github.com/jazzband/pip-tools?tab=readme-ov-file#pip-tools--pip-compile--pip-sync or the now much faster uv: https://docs.astral.sh/uv/reference/cli/#uv-pip