From 0bc540099d5d85d238916a7254490b1d40439610 Mon Sep 17 00:00:00 2001 From: meet-vasita Date: Fri, 29 Aug 2025 21:17:38 +0530 Subject: [PATCH 1/6] Fix inconsistent examples in dependency resolution docs --- docs/html/topics/dependency-resolution.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/docs/html/topics/dependency-resolution.md b/docs/html/topics/dependency-resolution.md index 45fb305e22d..8433c162cc8 100644 --- a/docs/html/topics/dependency-resolution.md +++ b/docs/html/topics/dependency-resolution.md @@ -165,6 +165,9 @@ will avoid performing dependency resolution during deployment. ## Dealing with dependency conflicts +This section uses imaginary packages (`package_coffee`, `package_tea`, and +`package_water`) to explain how pip resolves conflicts. + This section provides practical suggestions to pip users who encounter a `ResolutionImpossible` error, where pip cannot install their specified packages due to conflicting dependencies. @@ -194,6 +197,11 @@ because they each depend on different versions of the same package - ``package_tea`` version ``4.3.0`` depends on version ``2.3.1`` of ``package_water`` +Note: `package_coffee`, `package_tea`, and `package_water` are imaginary +packages used only to illustrate dependency conflicts. They are not real +projects you can install. + + Sometimes these messages are straightforward to read, because they use commonly understood comparison operators to specify the required version (e.g. `<` or `>`). @@ -252,10 +260,10 @@ the same version of `package_water`, you might consider: In the second case, pip will automatically find a version of both `package_coffee` and `package_tea` that depend on the same version of -`package_water`, installing: +`package_water`, for example: - `package_coffee 0.44.1`, which depends on `package_water 2.6.1` -- `package_tea 4.4.3` which _also_ depends on `package_water 2.6.1` +- `package_tea 4.4.3`, which also depends on `package_water 2.6.1` If you want to prioritize one package over another, you can add version specifiers to _only_ the more important package: From 0f222aeaa029388d61ca44d7f76018da27c4c4b3 Mon Sep 17 00:00:00 2001 From: meet-vasita Date: Fri, 29 Aug 2025 21:27:02 +0530 Subject: [PATCH 2/6] Add changelog entry for dependency resolution docs clarification --- news/13561.doc.rst | 1 + 1 file changed, 1 insertion(+) create mode 100644 news/13561.doc.rst diff --git a/news/13561.doc.rst b/news/13561.doc.rst new file mode 100644 index 00000000000..d75fcb18d09 --- /dev/null +++ b/news/13561.doc.rst @@ -0,0 +1 @@ +Clarified dependency resolution docs: added note on imaginary packages, fixed version mismatch, and added introduction line. From a4995eb4a9355c1ba627ff9e4c0ccd1d0f441849 Mon Sep 17 00:00:00 2001 From: meet-vasita Date: Sat, 30 Aug 2025 21:09:28 +0530 Subject: [PATCH 3/6] docs(pip_freeze): clarify --all; explain Python version differences --- src/pip/_internal/commands/freeze.py | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/src/pip/_internal/commands/freeze.py b/src/pip/_internal/commands/freeze.py index 7794857cf80..6f9dbcffa66 100644 --- a/src/pip/_internal/commands/freeze.py +++ b/src/pip/_internal/commands/freeze.py @@ -25,7 +25,7 @@ class FreezeCommand(Command): """ Output installed packages in requirements format. - packages are listed in a case-insensitive sorted order. + Packages are listed in a case-insensitive sorted order. """ ignore_require_venv = True @@ -70,15 +70,17 @@ def add_options(self) -> None: dest="freeze_all", action="store_true", help=( - "Do not skip these packages in the output:" - " {}".format(", ".join(_dev_pkgs())) + "Do not skip certain development-related packages in the output. " + "On Python 3.12 and later, only `pip` is skipped by default. " + "On Python 3.11 and earlier, the following packages are also " + "skipped by default: `setuptools`, `wheel`, and `distribute`." ), ) self.cmd_opts.add_option( "--exclude-editable", dest="exclude_editable", action="store_true", - help="Exclude editable package from output.", + help="Exclude editable packages from output.", ) self.cmd_opts.add_option(cmdoptions.list_exclude()) From 7eb3ee38936b370d0667300d4a3f782cfaf5a029 Mon Sep 17 00:00:00 2001 From: meet-vasita Date: Sat, 30 Aug 2025 21:28:44 +0530 Subject: [PATCH 4/6] docs(pip_freeze): clarify --all; explain Python version differences --- src/pip/_internal/commands/freeze.py | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/src/pip/_internal/commands/freeze.py b/src/pip/_internal/commands/freeze.py index 6f9dbcffa66..7794857cf80 100644 --- a/src/pip/_internal/commands/freeze.py +++ b/src/pip/_internal/commands/freeze.py @@ -25,7 +25,7 @@ class FreezeCommand(Command): """ Output installed packages in requirements format. - Packages are listed in a case-insensitive sorted order. + packages are listed in a case-insensitive sorted order. """ ignore_require_venv = True @@ -70,17 +70,15 @@ def add_options(self) -> None: dest="freeze_all", action="store_true", help=( - "Do not skip certain development-related packages in the output. " - "On Python 3.12 and later, only `pip` is skipped by default. " - "On Python 3.11 and earlier, the following packages are also " - "skipped by default: `setuptools`, `wheel`, and `distribute`." + "Do not skip these packages in the output:" + " {}".format(", ".join(_dev_pkgs())) ), ) self.cmd_opts.add_option( "--exclude-editable", dest="exclude_editable", action="store_true", - help="Exclude editable packages from output.", + help="Exclude editable package from output.", ) self.cmd_opts.add_option(cmdoptions.list_exclude()) From 9b6683651256ac480d20d7af6cd05e8fa02e3356 Mon Sep 17 00:00:00 2001 From: meet-vasita Date: Sat, 30 Aug 2025 21:31:49 +0530 Subject: [PATCH 5/6] docs(pip_freeze): clarify --all; explain Python version differences --- src/pip/_internal/commands/freeze.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/pip/_internal/commands/freeze.py b/src/pip/_internal/commands/freeze.py index 7794857cf80..18a878752b0 100644 --- a/src/pip/_internal/commands/freeze.py +++ b/src/pip/_internal/commands/freeze.py @@ -70,8 +70,10 @@ def add_options(self) -> None: dest="freeze_all", action="store_true", help=( - "Do not skip these packages in the output:" - " {}".format(", ".join(_dev_pkgs())) + "Do not skip these packages in the output. " + "On Python 3.12 and later, only `pip` is skipped by default. " + "On Python 3.11 and earlier, the following are also skipped: " + "`setuptools`, `wheel`, and `distribute`." ), ) self.cmd_opts.add_option( From c095e0ee64e3e61cf04d10e19e5e66da6b738fd0 Mon Sep 17 00:00:00 2001 From: meet-vasita Date: Sat, 30 Aug 2025 21:36:42 +0530 Subject: [PATCH 6/6] docs(pip_freeze): clarify --all; explain Python version differences --- docs/html/cli/pip_freeze.rst | 68 ++++++++++++++++------------ src/pip/_internal/commands/freeze.py | 6 +-- 2 files changed, 42 insertions(+), 32 deletions(-) diff --git a/docs/html/cli/pip_freeze.rst b/docs/html/cli/pip_freeze.rst index b90bcad70fb..7c5e19087b5 100644 --- a/docs/html/cli/pip_freeze.rst +++ b/docs/html/cli/pip_freeze.rst @@ -30,49 +30,61 @@ Options .. pip-command-options:: freeze + + +.. note:: + + By default, ``pip freeze`` omits pip's own bootstrap tools (``pip``, + ``setuptools``, and ``wheel``) to keep the output focused on project + dependencies. Use ``--all`` to include these as well, which is helpful when + capturing a full environment snapshot. Remember that ``pip freeze`` only + reports what is currently installed; it is not a lockfile or solver result. + + Examples ======== + env1\bin\python -m pip freeze > requirements.txt + env2\bin\python -m pip install -r requirements.txt -#. Generate output suitable for a requirements file. +#. Compare default output with ``--all``. .. tab:: Unix/macOS .. code-block:: console $ python -m pip freeze - docutils==0.11 - Jinja2==2.7.2 - MarkupSafe==0.19 - Pygments==1.6 - Sphinx==1.2.2 + certifi==... + idna==... + requests==... + urllib3==... + + $ python -m pip freeze --all + certifi==... + idna==... + requests==... + urllib3==... + pip==... + setuptools==... + wheel==... .. tab:: Windows .. code-block:: console C:\> py -m pip freeze - docutils==0.11 - Jinja2==2.7.2 - MarkupSafe==0.19 - Pygments==1.6 - Sphinx==1.2.2 - -#. Generate a requirements file and then install from it in another environment. - - .. tab:: Unix/macOS - - .. code-block:: shell - - env1/bin/python -m pip freeze > requirements.txt - env2/bin/python -m pip install -r requirements.txt - - .. tab:: Windows - - .. code-block:: shell - - env1\bin\python -m pip freeze > requirements.txt - env2\bin\python -m pip install -r requirements.txt - + certifi==... + idna==... + requests==... + urllib3==... + + C:\> py -m pip freeze --all + certifi==... + idna==... + requests==... + urllib3==... + pip==... + setuptools==... + wheel==... Fixing "Permission denied:" errors ================================== diff --git a/src/pip/_internal/commands/freeze.py b/src/pip/_internal/commands/freeze.py index 18a878752b0..7794857cf80 100644 --- a/src/pip/_internal/commands/freeze.py +++ b/src/pip/_internal/commands/freeze.py @@ -70,10 +70,8 @@ def add_options(self) -> None: dest="freeze_all", action="store_true", help=( - "Do not skip these packages in the output. " - "On Python 3.12 and later, only `pip` is skipped by default. " - "On Python 3.11 and earlier, the following are also skipped: " - "`setuptools`, `wheel`, and `distribute`." + "Do not skip these packages in the output:" + " {}".format(", ".join(_dev_pkgs())) ), ) self.cmd_opts.add_option(