What is pip?

pip is the standard package installer for Python, bundled with every modern Python installation (3.4+). It installs packages from the Python Package Index (PyPI) or any compatible index, resolves dependencies, and manages them inside whatever Python environment is currently active — a system install, a virtual environment, or a container.

Unlike newer tools such as UV or Poetry, pip is deliberately minimal: it installs and uninstalls packages and does not natively manage virtual environments, lockfiles, or Python versions on its own. Those responsibilities are traditionally handled by companion tools (venv, virtualenv, pip-tools, pyenv). This cheatsheet covers pip itself plus the adjacent standard-library tools most commonly paired with it, so you have the full “classic” Python workflow in one place: installing and upgrading pip, installing and removing packages, working with requirements files, inspecting installed packages, creating virtual environments, and freezing/compiling reproducible dependency sets.

Checking and Upgrading pip

python -m pip --version          # check the installed pip version and which Python it's tied to
python3 -m pip --version         # same, explicit python3 (useful when both python/python3 exist)

python -m pip install --upgrade pip   # upgrade pip itself to the latest version
python -m pip install pip==23.3.1     # install a specific pip version

Running pip as python -m pip (rather than a bare pip command) is the safer habit — it guarantees you’re using the pip tied to the Python interpreter you intend, which matters a lot once multiple Python versions are installed on one machine.

Installing Packages

pip install requests                  # install the latest compatible version
pip install requests==2.31.0          # install an exact version
pip install "requests>=2.25,<3"       # install within a version range
pip install requests flask numpy      # install multiple packages at once

pip install --upgrade requests        # upgrade an already-installed package
pip install -U requests               # shorthand for --upgrade

pip install -e .                      # install the current directory in editable/development mode
pip install -e ./my-package           # editable install of a local package path

pip install git+https://github.com/org/repo.git           # install directly from a git repo
pip install git+https://github.com/org/repo.git@v1.2.0    # install a specific tag/branch/commit

pip install ./some_package.whl        # install from a local wheel file
pip install ./some_package.tar.gz     # install from a local source distribution

pip install --index-url https://my.private.index/simple/ requests   # use a custom package index
pip install --extra-index-url https://my.private.index/simple/ requests  # add a secondary index
pip install --no-deps requests        # install without pulling in dependencies
pip install --no-cache-dir requests   # install without using pip's local cache

Uninstalling Packages

pip uninstall requests         # uninstall a package (prompts for confirmation)
pip uninstall -y requests      # uninstall without a confirmation prompt
pip uninstall -r requirements.txt -y   # uninstall everything listed in a requirements file

Requirements Files

Requirements files are plain text files listing dependencies, one per line, and are the traditional way to make an environment reproducible across machines and CI.

pip install -r requirements.txt       # install everything listed in the file
pip install -r requirements.txt -r requirements-dev.txt   # install from multiple files

pip freeze > requirements.txt         # write currently installed packages + versions to a file
pip freeze --local > requirements.txt # exclude globally installed packages, only this env's

A typical requirements.txt looks like this:

requests==2.31.0
flask>=2.3,<3.0
numpy
# comments are allowed with a leading #
-e ./local-package

Note that pip freeze captures only what’s currently installed — it doesn’t distinguish top-level dependencies you asked for from transitive ones pulled in automatically, and it doesn’t produce a cross-platform lockfile. For fully reproducible, hash-pinned dependency resolution, the companion tool pip-tools (see below) or a more modern tool like UV or Poetry is generally preferred over raw pip freeze.

Inspecting Installed Packages

pip list                        # list all installed packages and their versions
pip list --outdated             # show packages that have a newer version available
pip list --format=json          # machine-readable output

pip show requests               # show metadata: version, location, dependencies, etc.
pip show -f requests            # also list every file the package installed

pip check                       # verify installed packages have no dependency conflicts

Virtual Environments

pip itself doesn’t create virtual environments — that’s the job of the standard-library venv module (or the older third-party virtualenv). Using a virtual environment per project is strongly recommended so dependencies don’t collide across projects or pollute your system Python.

python -m venv .venv                  # create a virtual environment in ./.venv
python -m venv .venv --prompt myapp   # create it with a custom shell prompt label

source .venv/bin/activate             # activate on macOS/Linux
.venv\Scripts\activate                # activate on Windows (cmd)
.venv\Scripts\Activate.ps1            # activate on Windows (PowerShell)

deactivate                            # leave the active virtual environment

pip install virtualenv                # install the third-party alternative, if preferred
virtualenv .venv                      # create an env with virtualenv instead of venv

Once a virtual environment is activated, every pip install runs inside it rather than touching your system-wide Python — this is the standard way to keep per-project dependencies isolated.

Constraints Files

Constraints files let you cap or pin versions globally across an install without necessarily requesting those packages directly — useful for enforcing a known-good version of a transitive dependency.

pip install -r requirements.txt -c constraints.txt

# constraints.txt
urllib3<2.0

pip-tools (compiling locked requirements)

pip-tools is a popular companion package (install separately) that adds pip-compile and pip-sync commands, giving pip-based workflows something closer to a real lockfile.

pip install pip-tools                  # install the pip-tools package

pip-compile requirements.in            # resolve requirements.in into a fully pinned requirements.txt
pip-compile --upgrade requirements.in  # re-resolve and upgrade all pinned versions
pip-compile --upgrade-package requests requirements.in  # upgrade just one package

pip-sync requirements.txt              # make the environment match requirements.txt exactly,
                                        # installing/removing packages as needed

Configuration

pip reads configuration from a config file so you don’t have to repeat flags like --index-url on every command.

# pip.conf (Linux/macOS: ~/.config/pip/pip.conf, Windows: %APPDATA%\pip\pip.ini)
[global]
index-url = https://my.private.index/simple/
timeout = 60

pip config list                       # show current configuration
pip config set global.index-url https://my.private.index/simple/   # set a config value
pip config unset global.index-url     # remove a config value

Useful Environment Variables

Environment VariablePurpose
PIP_INDEX_URLDefault package index to install from
PIP_EXTRA_INDEX_URLAdditional package index(es) to search
PIP_NO_CACHE_DIRDisable pip’s local wheel/package cache
PIP_REQUIRE_VIRTUALENVRefuse to install outside an active virtual environment
PIP_DEFAULT_TIMEOUTNetwork timeout in seconds for pip operations

Cache Management

pip cache dir             # show where pip's cache lives on disk
pip cache list             # list what's cached
pip cache remove requests  # remove cached wheels/files matching a pattern
pip cache purge            # clear the entire cache

Troubleshooting Tips

  • If pip install seems to affect the wrong Python, run it as python -m pip install ... to be certain which interpreter is targeted, and confirm with python -m pip --version.
  • If you hit a SSLCertVerificationError or similar on a managed network, it’s usually a corporate proxy/certificate issue rather than a pip bug — check with your network/security team before disabling verification.
  • Use pip check after a manual install or uninstall to catch dependency conflicts early.
  • If an install seems to hang or use a stale cached file, retry with --no-cache-dir to force a fresh download.
  • Add -v or -vvv to most commands for increasingly verbose output when diagnosing a failed install.
  • Always prefer installing into an active virtual environment over a system-wide install — it avoids permission issues and keeps unrelated projects from interfering with each other.

Quick End-to-End Workflow Example

python -m venv .venv                  # create a virtual environment
source .venv/bin/activate             # activate it
python -m pip install --upgrade pip   # make sure pip itself is current
pip install flask pytest              # install runtime + dev dependencies
pip freeze > requirements.txt         # snapshot exact versions for reproducibility
pip check                             # verify no dependency conflicts
pytest                                # run the test suite

Created using Anthropic Claude. Verify commands against the latest pip documentation before relying on them, as CLI details may change between releases.