Skip to content

pip

The standard Python package installer. Use it inside a virtual environment — never into system Python.

Table of Contents

Installation / Setup

pip ships with Python 3.4+ (via ensurepip). Prefer python -m pip so you target the interpreter you mean.

python -m pip --version
python -m pip install --upgrade pip     # keep pip current

If pip is missing: python -m ensurepip --upgrade. (Windows full installer includes pip; on some Linux distros: sudo apt install python3-pip.)

Prefer the modern alternative uv if you want speed and lockfiles.

Core Syntax

Command What it does
pip install pandas Install latest version
pip install "pandas>=2.0,<3" Version range
pip install "pandas==2.2.2" Exact version (pin)
pip install scikit-learn[extra] Install with extras (e.g. [gpu], [dev])
pip install -r requirements.txt Install a file of requirements
pip install -e . Editable install of current project
pip install --upgrade pandas Upgrade to latest
pip uninstall pandas Remove
pip list Installed packages
pip show pandas Details: version, location, deps
pip check Verify no broken dependencies
pip freeze Exact versions of everything (for requirements.txt)
pip cache list / pip cache purge Manage the download cache

Requirement specifiers

pandas                        # any version
pandas==2.2.2                 # exact
pandas>=2.0                   # minimum (compatible release)
pandas>=2.0,<3                # range
numpy==1.26.*                 # wildcard
-e .                          # the project itself (editable)

Common Operations

Install for data science

python -m venv .venv && source .venv/bin/activate
pip install numpy pandas scikit-learn matplotlib jupyter

Install PyTorch with the right CUDA build

pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

Generate and use requirements files

pip freeze > requirements.txt                  # exact, full snapshot
pip install -r requirements.txt                # reproduce elsewhere

pip-tools for clean requirement management

pip install pip-tools
pip-compile requirements.in                    # -> requirements.txt (pinned)
pip-sync requirements.txt                      # make env match exactly

Practical Examples

1. Reproducible environment for a project

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt
pip check

2. Install a package from GitHub

pip install git+https://github.com/user/repo.git
pip install git+https://github.com/user/repo.git@v1.2.3   # pinned tag

3. Install from a local wheel

pip install ./dist/mypkg-1.0-py3-none-any.whl

Common Patterns

# requirements.in — human-readable intent
pandas>=2.0
scikit-learn
streamlit

# requirements.txt — generated by pip-compile, exact pins
pandas==2.2.2
numpy==1.26.4
...

# Dev-only deps in a separate file
pip install -r requirements-dev.txt    # pytest, mypy, ruff, pre-commit

Best Practices

  • Always install inside a venv — see python-virtual-environments.md.
  • Pin exact versions in generated files; write ranges in hand-maintained files.
  • Prefer python -m pip over bare pip — it always targets the active interpreter.
  • Don't use sudo pip install — use a venv instead (system Python is managed by the OS).
  • Use pip check after installs to catch dependency conflicts early.
  • Use --no-cache-dir in CI to keep builds clean: pip install --no-cache-dir -r requirements.txt.
  • For serious reproducibility, graduate to a lockfile via pip-tools or uv.

Common Mistakes

Mistake Consequence Correct approach
Installing into system Python Conflicts with OS packages (PEP 668 blocks on many distros) Create a venv
sudo pip install Permissions mess, broken system Python venv (no sudo)
pip install not python -m pip Installs into a different Python Use python -m pip
Unpinned requirements Non-reproducible environments Pin or compile
pip freeze on a polluted env Huge requirements with junk Freeze inside a fresh venv
Mixing PyTorch CUDA wheels Wrong CUDA build / errors on import Match --index-url to your CUDA version

Troubleshooting

Symptom Cause Fix
ERROR: externally-managed-environment OS Python protected (PEP 668) Create a venv
ERROR: No matching distribution found for pandas Typo, no network, or bad index Check name/pip index versions pandas
error: externally-managed or permissions on install Installing globally venv
pip: command not found pip not on PATH python -m pip
Conflicting dependencies (pip check fails) Version clash Create fresh venv; let resolver pick compatible set
SSL / proxy errors Network restrictions Configure proxy: pip install --proxy http://host:port pkg

Official Documentation

Last Updated

2026-09-06 — Initial version.