pip#

The package installer for Python, pip, is used to install packages from PyPI and other sources.

Usage#

Running pip#

The pip tool should be included in your Python installation. Otherwise check their installation instructions. You can check its version and installation path.

$ pip --version
pip X.Y.Z from /path/to/site-packages/pip (python 3.11)

Instead of using the pip command directly you can also call the Python interpreter with the pip module.

$ python -m pip --version

This syntax allows you to easily select the pip for any given Python installation.

Upgrading pip#

On some systems you may want to upgrade pip to the latest version. It’s usually safest to do this inside the user scheme, as it does not require admin rights or affect the system-wide installation.

$ python -m pip install --user --upgrade pip
...
Sucessfully installed pip-X.Y.Z
$ python -m pip --version
pip X.Y.Z from /home/johndoe/.local/lib/python3.11/site-packages/pip (python 3.11)

Note how the pip installation path resides inside the user’s home in ~/.local/lib/.

Important

Depending on how Python was installed on your system, pip may warn or even fail when used outside of a virtual environment, regardless of the --user flag. The underlying reason is that PEP 668 allows the system Python to be flagged as “externally-managed” and redirecting users to virtual environments instead of interfering with the system installation. Please consider migrating to proper venvs and disregard the --break-system-packages flag to make pip install packages nevertheless. The goal of PEP 704 is to require virtual environments by default in Python 3.13+.

Installing packages#

The most common task is to install Python packages, either in their most recent version,

$ pip install <package>

or with a specific version number.

$ pip install <package>==2.0

Another common usecase is to install a Python package directly from a locally checked out git repository. Combined with the -e flag, the package is installed in “editable mode”, where all modifications in the repo become directly available in the installed package. This simplifies active development in a project, while also keeping it installed as dependency for related projects.

$ git clone git@github.com:path/to/py-project.git
$ pip install -e py-project/

Tip

Some packages have C or Fortran bindings that may need to be compiled from source. This can require additional compilers and header files to be installed on your computer.

Most packages are also distributed as pre-built wheels. Installing a package using such binary files skips the requirement to compile from source, thereby making the installation much faster and simpler. Please make sure you have the wheel package installed.

$ pip install wheel

In case you explicitly want to compile from source (for instance to have platform-dependent optimizations), use the --no-binary flag.

$ pip install --no-binary :all: <package>

Changing package installation path#

If you have admin rights, pip typically installs all packages to a system-wide location. With the additional --user option the packages are installed into the user’s home (eg ~/.local/lib/ on Unix). This allows users without admin rights to install Pyhton packges.

In rare cases you may want to install a specific package and “bundle” it with a project’s code by installing it into a vendor/ sub-directory.

$ pip install SomePackage -t vendor

The package can then be imported by prepending vendor/ to the sys.path.

import sys
sys.path.insert(0, "vendor")
import SomePackage

Working with requirements.txt#

It’s common practice to include a requirements.txt file in a Python project, that specifies the list of required packages and, if needed, the compatible versions thereof. The motivation is to ensure full portability and reproducibility of the code, as every user can install exactly the same packages.

some_package
other_package==1.0

The following pip command installs all packages listed in the requirements.txt file.

$ pip install -r requirements.txt

Conversely you can use pip freeze to generate a requirements.txt file from the currently installed packages.

$ pip freeze > requirements.txt

Upgrading packages#

Any given package can be upgraded to the latest version using the --upgrade (or -U) switch.

$ pip install --upgrade <package>

Other helpful commands#

pip list              # show list of installed packages and their versions
pip list --outdated   # show list of packages with available upgrades
pip show <package>    # show info about installed package
pip show -f <package> # show info and include list of files
pip uninstall <pkg>   # uninstall given package
pip cache info        # show info and size of pip cache folder
pip cache purge       # delete pip cache folder
pip --no-cache-dir <cmd>    # run pip command without using any cache