Gecko [ tsuru-no-tsurugi.tokyo ]

Name	Size	Permission	Date
html	[ DIR ]	drwxr-xr-x	2025-12-31 20:37
man	[ DIR ]	drwxr-xr-x	2025-12-31 20:37
README.Debian	2.19 KB	-rw-r--r--	2022-02-03 01:00
changelog.Debian.gz	1.42 KB	-rw-r--r--	2025-09-23 04:44
copyright	18.4 KB	-rw-r--r--	2022-02-03 01:00
pip_sphinxext.py.gz	2.84 KB	-rw-r--r--	2022-01-31 07:46
requirements.txt	246 B	-rw-r--r--	2022-01-31 07:46

Rename

pip on Debian is a crazy mess due to upstream's vendorizing of several
packages, which violates both the DFSG and Debian Policy.  To resolve this
conflict, we package up these dependencies as PEP 427 wheels, essentially zip
files containing importable pure-Python code and a metadata directory.  These
wheels live in separate python-<pkg>-whl binary packages, and are installed
into /usr/share/python-wheels.

These wheels are not used when running pip outside of a virtual environment
(venv).  In that case, it pip just uses the normal sys.path, on which it finds
the dependencies installed into Debian's system Pythons in the normal way.
However, an "outside-the-venv" pip cannot be used to install packages inside
the venv, so the two main venv creation tools, virtualenv and pyvenv, make
sure that the virtualenv has a pip executable, but of course in different
ways.

It gets trickier inside a venv, which by definition may be isolated from the
system Python's sys.path.  In this case, Debian's inside-the-venv pip prepends
the paths to the -whl files onto the front of sys.path, so that imports will
Just Work and upgrades to the dependencies inside the venv won't break pip.
(Yes, this can and has happened and we need to guard against it.)

It's important to note that determining whether you are in a venv is a
heuristic labyrinth, because the things you need to check are different
between Python 2 and Python 3, and between virtualenv and pyvenv (Python
3-only).  I think we've got it right <wink>.

Python 3.4 introduced a module called "ensurepip" which is used - as its name
describes - to ensure that there is a pip executable inside the pyvenv created
venv.  ensurepip does this job by copying all of the dependent .whl files from
/usr/share/python-wheels into the venv, where pip will look to put then on the
front of sys.path.

See Debian Python Policy $3.2 for additional details.

As of python3-pip 20.1-1, sys.base_prefix is used by Debian's pip to find the
unvendored wheels, so they are no longer copied into a virtualenv when it is
created.  To locally install these wheels in a virtualenv using pip, you can
use the --extra-search-dir option in pip to specify /usr/share/python-wheels
as a location to install from.