Conflicting instructions between manpages and running help on the command

Question

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:

• Is this a bug with Ubuntu or Pip? If so, should I report it?
• Does Pip not use manpages any more?
• If the manpages are no longer maintained / out-of-date, why are they even there?

• KamilCuk: firstly, pip != python. Your post is about pip man pages, but then you ask about python.
• Steve Lorimer: @KamilCuk Yeah, apologies - clearly I'm a bit new to the ecosystem - I'll modify the question
• tink: Given the age of the man-pages (2014) I'd blame the package maintainers. Whether it's debian or ubuntu ... ?

Answer 1

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.

• Steve Lorimer: Thanks - so suggests I should report this as a bug to pip
• Steve Lorimer: I've installed python-is-python3, so pip and python etc are the v3 versions. $ pip --version reports pip 22.0.2 from /usr/lib/python3/dist-packages/pip (python 3.10)