PIP(1)

📦 version 20.3.4, in ubuntu jammy

okay so you clicked on pip(1) and honestly? iconic choice 💅 this is the manual page for pip, and we're gonna walk through it together, no gatekeeping, no cap. grab a boba 🧋 and let's go.

🌸 NAME 🌸

pip — a tool for installing and managing Python packages 🐍✨

✨ SYNOPSIS ✨

pip <command> [options]

pip3 <command> [options]

that's it. that's the whole vibe. command first, options after 🎀

💖 DESCRIPTION 💖

pip is a Python package installer, and on Debian it's the one you want for installing Python packages that aren't chillin' in the Debian archive. she's versatile bestie:

  • she can work with version control repositories — currently only Git, Mercurial, and Bazaar 👑
  • she logs output extensively, like she's keeping receipts fr fr
  • and she prevents partial installs by downloading all the requirements before she starts installing anything. no half-finished messes. we love a girl with a plan 🫶

now the important Debian-specific tea ☕: on Debian, pip is the command you use when you're installing packages for Python 2, while pip3 is the command you use when you're installing packages for Python 3. don't mix them up, the vibe check will not pass 😭

🎀 COMMANDS 🎀

the command comes before any options. it's giving opening act energy. here's what's recognized:

  • help — show help for commands 🙋
  • install — install packages 📦
  • uninstall — uninstall packages 🗑️
  • freeze — output installed packages in requirements format 🧊
  • list — list installed packages 📝
  • show — show information about installed packages 🔍
  • search — search PyPI for packages 🔎
  • wheel — build wheels from your requirements 🛞

💅 GENERAL OPTIONS 💅

real talk: this list is by no means complete, and it only describes options that are available to all commands. if you want more details on command-specific options, run pip <command> --help. a few command options are provided below tho, as a lil treat 🍓

  • -h, --help — show more detailed command help
  • -v, --verbose — give more output. this option is additive, so you can stack it up to 3 times 🔥
  • -V, --version — show version and exit
  • -q, --quiet — give less output. shhh 🤫
  • --log-file <path> — path to a verbose non-appending log that only logs failures. this log is active by default at ~/.pip/pip.log
  • --log <path> — path to a verbose appending log. this one is inactive by default
  • --proxy <proxy> — specify a proxy in the form [user:passwd@]proxy.server:port
  • --timeout <sec> — set the socket timeout (default 15 seconds) ⏳
  • --exists-action <action> — default action when a path already exists: (s)witch, (i)gnore, (w)ipe, (b)ackup
  • --cert <path> — path to alternate CA bundle 🔐

🦋 INSTALL OPTIONS 🦋

pip install installs packages from all these places:

  • PyPI (a.k.a. The Cheeseshop 🧀) and other indexes, using requirements specifiers
  • VCS project urls
  • local project directories
  • local or remote source archives
  • local wheel directories — python-pip-whl installs its wheels in /usr/share/python-wheels and they can be locally installed by pip using --find-links 👑

now the options, and yes we're doing all of them:

  • -e,--editable <path/url> — install a project in editable mode (i.e. setuptools "develop mode") from a local project path or a VCS url
  • -r,--requirement <file> — install from the given requirements file. this option can be used multiple times 🔁
  • -b,--build <dir> — directory to unpack packages into and build in. the default in a virtualenv is <venv path>/build. the default for global installs is <OS temp dir>/pip_build_<username>
  • -t,--target <dir> — install packages into <dir>
  • -d,--download <dir> — download packages into <dir> instead of installing them, regardless of what's already installed
  • --download-cache <dir> — cache downloaded packages in <dir>
  • --src <dir> — directory to check out editable projects into. the default in a virtualenv is <venv path>/src. the default for global installs is <current dir>/src
  • -U, --upgrade — upgrade all packages to the newest available version. this process is recursive regardless of whether a dependency is already satisfied
  • --force-reinstall — when upgrading, reinstall all packages even if they are already up-to-date
  • -I, --ignore-installed — ignore the installed packages (reinstalling instead)
  • --no-deps — don't install package dependencies
  • --install-option <options> — extra arguments to be supplied to the setup.py install command (use like --install-option ="--install-scripts=/usr/local/bin"). use multiple --install-option options to pass multiple options to setup.py install. if you are using an option with a directory path, be sure to use absolute path
  • --global-option <options> — extra global options to be supplied to the setup.py call before the install command
  • --user — install using the user scheme
  • --egg — install packages as eggs, not 'flat', like pip normally does. this option is not about installing from eggs.
⚠️ WARNING: because this option overrides pip's normal install logic, requirements files may not behave as expected. 😭 proceed with caution bestie
  • --root <dir> — install everything relative to this alternate root directory
  • --compile — compile py files to pyc
  • --no-compile — do not compile py files to pyc
  • --no-use-wheel — do not find and prefer wheel archives when searching indexes and find-links locations
  • --pre — include pre-release and development versions. by default, pip only finds stable versions 🧚
  • --no-clean — don't clean up build directories

⭐ Package Index Options ⭐

  • -i,--index-url <url> — base URL of Python Package Index (default https://pypi.python.org/simple/)
  • --extra-index-url <url> — extra URLs of package indexes to use in addition to --index-url
  • --no-index — ignore package index (only looking at --find-links URLs instead)
  • -f,--find-links <url> — if a url or path to an html file, then parse for links to archives. if a local path or file:// url that's a directory, then look for archives in the directory listing 👀
  • --allow-external <package> — allow the installation of externally hosted files
  • --allow-all-external — allow the installation of all externally hosted files
  • --allow-unverified <package> — allow the installation of insecure and unverifiable files
🚨 bestie, note the words "insecure" and "unverifiable" — that's the whole point of the flag, so know what you're signing up for
  • --process-dependency-links — enable the processing of dependency links

💀 UNINSTALL OPTIONS 💀

pip is able to uninstall most installed packages. known exceptions are:

  • pure distutils packages installed with python setup.py install, which leave behind no metadata to determine what files were installed 😭
  • script wrappers installed by python setup.py develop
  • -r,--requirement <file> — uninstall all the packages listed in the given requirements file. this option can be used multiple times 🔁
  • -y, --yes — don't ask for confirmation of uninstall deletions. she's just gonna do it 💅

🌈 AUTHORS 🌈

this manual page was originally written by Jeff Licquia <licquia@debian.org>, later rewritten by Carl Chenet <chaica@debian.org>. it was rewritten again and the source converted to reStructuredText by Barry Warsaw <barry@debian.org>. three authors, one glow-up ✨

permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License, version 3 or any later version published by the Free Software Foundation. 📜

👑 AUTHOR 👑

Barry Warsaw <barry@debian.org>

and that's the whole page, bestie 🫶 this was PIP(1), version 1.5.6, dated 2014-06-03 — yes she's a vintage queen and she still ate 💖 go forth and install responsibly 🎀

📦 where this page comes from