CODEWITHSUNDEEP
pythonlinuxpipmanpage
Steve Lorimer
Steve Lorimer

Reputation: 28689

Conflicting instructions between manpages and running help on the command

I was recently trying to understand why running pip install --upgrade wasn't upgrading some packages in my virtualenv.

Being on Ubuntu 22.04, I turned to the manpages for help.

There I found the following:

-U, --upgrade
    Upgrade all packages to the newest available version.  
    This process is recursive regardless of whether a dependency is already satisfied.

This didn't seem to be the case, so I was feeling a bit lost.

I checked where the manpages were coming from, and they were the system install location

$ man -w pip
/usr/share/man/man1/pip3.1.gz

Eventually I found pip --help, which in turn led me to pip help install

Here I found different instructions on how to upgrade packages:

 -U, --upgrade    Upgrade all specified packages to the newest available version.
                  The handling of dependencies depends on the upgrade-strategy used.

  --upgrade-strategy <upgrade_strategy>
                  Determines how dependency upgrading should be handled [default: only-if-needed].
                  "eager"          dependencies are upgraded regardless of whether the currently installed
                                   version satisfies the requirements of the upgraded package(s). 
                  "only-if-needed" are upgraded only when they do not satisfy the requirements of the 
                                   upgraded package(s).

By specifying an eager upgrade strategy, I am now able to replicate the behaviour as described in the manpages.

My conclusion is that the manpages are incorrect / out-of-date

Questions:

Upvotes: -1

Views: 54

Answers (1)

KamilCuk
KamilCuk

Reputation: 141698

Is this a bug with Ubuntu or Python?

No.

[Is this a bug with pip?]

No.

Does Python not use manpages any more?

No, cpython project ships with a man page https://github.com/python/cpython/blob/main/Misc/python.man .

[Does pip not use manpages any more?]

No, pip project ships with man pages https://github.com/pypa/pip/tree/main/docs/man/commands .

why are they even there?

Because the pip maintainer added them.

What I see is that pip man pages are generated by sphinx https://github.com/pypa/pip/commit/bf4c613071eaf44e2cea249396b9e11d8baa32d3#diff-ef2cef9f88b4fe09ca3082140e67f5ad34fb65fb6e228f119d3812261ae51449 . So they will always contain the same.

You are most probably are viewing a man page for pip3 from python3 but using pip from python2 (or other way round). Check your pip3 install --help.

Upvotes: 0

Related Questions