pip is the tool used to install Python packages, and it is installed as part of your Python installation. pip supposedly is a recursive acronym that stands for Pip Installs Python or Pip Installs Packages. (Programmers can be pretty nerdy with their humor.) If you have more than one version of Python installed on your system, each version has its own pip package manager.
By default, when you run pip install something, pip will:
This is a gross understatement of what pip does—it also does cool stuff like setting up scripts defined by the package, wheel caching, and more.
As mentioned, each installation of Python has its own version of pip tied to it. If you’re using virtual environments, pip and python are automatically linked to whichever Python version you specified when creating the virtual environment. If you aren’t using virtual environments, and you have multiple Python versions installed, such as python3.5 and python3.6, you will probably want to use python3.5 -m pip or python3.6 -m pip instead of pip directly. It works just the same. (For the examples in this appendix, I assume you are using virtual environments so that pip works just fine as-is.)
To check the version of pip and which version of Python it’s tied to, use pip --version:
| | (my_env) $ pip --version |
| | pip 9.0.1 from /path/to/code/my_env/lib/python3.6/site-packages (python 3.6) |
To list the packages you have currently installed with pip, use pip list. If there’s something there you don’t want anymore, you can uninstall it with pip uninstall something.
| | (my_env) $ pip list |
| | pip (9.0.1) |
| | setuptools (36.2.7) |
| | wheel (0.29.0) |
| | (my_env) $ pip install pytest |
| | ... |
| | Installing collected packages: py, pytest |
| | Successfully installed py-1.4.34 pytest-3.2.1 |
| | (my_env) $ pip list |
| | pip (9.0.1) |
| | py (1.4.34) |
| | pytest (3.2.1) |
| | setuptools (36.2.7) |
| | wheel (0.29.0) |
As shown in this example, pip installs the package you want and also any dependencies that aren’t already installed.
pip is pretty flexible. It can install things from other places, such as GitHub, your own servers, a shared directory, or a local package you’re developing yourself, and it always sticks the packages in site-packages unless you’re using Python virtual environments.
You can use pip to install packages with version numbers from http://pypi.python.org if it’s a release version PyPI knows about:
| | $ pip install pytest==3.2.1 |
You can use pip to install a local package that has a setup.py file in it:
| | $ pip install /path/to/package |
Use ./package_name if you are in the same directory as the package to install it locally:
| | $ cd /path/just/above/package |
| | $ pip install my_package # pip is looking in PyPI for "my_package" |
| | $ pip install ./my_package # now pip looks locally |
You can use pip to install packages that have been downloaded as zip files or wheels without unpacking them.
You can also use pip to download a lot of files at once using a requirements.txt file:
| | (my_env) $ cat requirements.txt |
| | pytest==3.2.1 |
| | pytest-xdist==1.20.0 |
| | (my_env) $ pip install -r requirements.txt |
| | ... |
| | Successfully installed apipkg-1.4 execnet-1.4.1 pytest-3.2.1 pytest-xdist-1.20.0 |
You can use pip to download a bunch of various versions into a local cache of packages, and then point pip there instead of PyPI to install them into virtual environments later, even when offline.
The following downloads pytest and all dependencies:
| | (my_env) $ mkdir ~/.pipcache |
| | (my_env) $ pip download -d ~/pipcache pytest |
| | Collecting pytest |
| | Using cached pytest-3.2.1-py2.py3-none-any.whl |
| | Saved /Users/okken/pipcache/pytest-3.2.1-py2.py3-none-any.whl |
| | Collecting py>=1.4.33 (from pytest) |
| | Using cached py-1.4.34-py2.py3-none-any.whl |
| | Saved /Users/okken/pipcache/py-1.4.34-py2.py3-none-any.whl |
| | Collecting setuptools (from pytest) |
| | Using cached setuptools-36.2.7-py2.py3-none-any.whl |
| | Saved /Users/okken/pipcache/setuptools-36.2.7-py2.py3-none-any.whl |
| | Successfully downloaded pytest py setuptools |
Later, even if you’re offline, you can install from the cache:
| | (my_env) $ pip install --no-index --find-links=~/pipcache pytest |
| | Collecting pytest |
| | Collecting py>=1.4.33 (from pytest) |
| | ... |
| | Installing collected packages: py, pytest |
| | Successfully installed py-1.4.34 pytest-3.2.1 |
This is great for situations like running tox or continuous integration test suites without needing to grab packages from PyPI. I also use this method to grab a bunch of packages before taking a trip so that I can code on the plane.
The Python Packaging Authority documentation[34] is a great resource for more information on pip.