pip Cheat Sheet

01Invoke pip Correctlybefore anything else

python -m pip install requests
Always this form. A bare pip may belong to a different interpreter than the python you're about to run.★
python -m pip --version
Prints pip's version and the Python it will install into. Read the second half.★
python -m pip install -U pip
Upgrade pip itself.
pip --python /path/to/python list
Drive a different interpreter's environment from this one.
pip config list
Every config file and env var currently in effect. Start debugging here.

02Virtual Environmentspip has no isolation of its own

python -m venv .venv
pip installs into whatever Python it's attached to. A venv is what makes that safe.★
source .venv/bin/activate
Windows: .venv\Scripts\activate. Then deactivate to leave.★
.venv/bin/python -m pip install -r requirements.txt
No activation needed — call the venv's interpreter directly. Best for scripts & CI.
pipx install ruff
For CLI tools, not libraries. Each gets its own hidden venv.
pip install --break-system-packages x
The PEP 668 override. Can break apt/Homebrew. Disposable containers only.last resort

03Installthe daily loop

pip install requests
Newest compatible release, plus its dependencies.★
pip install "requests==2.32.3"
Pin exactly. See card 05 for the full operator set.★
pip install -r requirements.txt
Install a whole file of specs.★
pip install -U requests
--upgrade. Note: it does not upgrade dependencies unless they're too old.
pip install -e .
Editable. Your source dir is linked in — edits take effect with no reinstall.★
pip install .
Build the current project and copy it in. A snapshot, not a link.
pip install --dry-run --report r.json x
Resolve, change nothing, dump the plan as JSON.
pip install --no-deps x
Just this package. Pairs with a fully-pinned lockfile.

04Where It Comes Fromindex, VCS, disk

pip install -i https://my.co/simple x
--index-url replaces PyPI.
pip install --extra-index-url URL x
Adds an index. Careful: a public PyPI name can shadow your private one.
pip install "proj @ git+https://github.com/o/r@v1.2"
Straight from a tag, branch or commit.
pip install ./dist/pkg-1.0-py3-none-any.whl
A local wheel. No index touched.
pip install --no-index -f ./wheels -r req.txt
Fully offline, from a wheelhouse directory.
pip index versions requests
Which versions exist. pip search is dead — PyPI removed that API.

05Version OperatorsPEP 440

requests==2.32.3
Exactly this version. What pip freeze emits.★
requests==2.32.*
Any release starting 2.32.
requests~=2.32.3
Compatible release — means >=2.32.3, ==2.32.*. See the diagram below.★
"requests>=2.28,<3"
A range. Comma is AND. Quote it — the shell eats < and >.★
"requests!=2.30.0"
Exclude one bad release.
pip install --pre x
Pre-releases are ignored by default; this opts in.

06Extras & MarkersPEP 508

pip install "fastapi[standard]"
Extras — optional dependency bundles the package declares.★
pip install "pkg[dev,test]"
Several at once.
pip install -e ".[dev]"
Your own project, editable, with its dev extra. The standard dev-setup line.★
pkg; python_version < "3.12"
Environment marker — install only where the condition holds.
pkg; sys_platform == "win32"
Also: platform_machine, implementation_name, os_name.
pip install --group dev
PEP 735 dependency-group from pyproject.toml.

07Inspect the Environmentwhat's actually in there

pip list
Everything installed, with versions.★
pip list --outdated
What has a newer release available.★
pip list --not-required
Top-level only — nothing else depends on these. The real "what did I ask for".★
pip show requests
Version, location, Requires: and Required-by:.
pip show -f requests
Every file the package installed.
pip check
Are the installed deps mutually consistent? Run after any manual surgery.★
pip inspect
The whole environment as machine-readable JSON.

08Requirements Filesthe -r format

pip freeze > requirements.txt
Dumps everything installed, pinned. Convenient, blunt — it can't tell your intent from a transitive dep.★
-r base.txt
Requirements files can include each other. dev.txt starts with -r base.txt.
-e .
Editable lines are legal inside a requirements file too.
--hash=sha256:abc…
Add one hash and pip switches the whole file into hash-checking mode.
pip install -c constraints.txt -r req.txt
Constraints only cap versions — they never cause an install. Use them to pin transitive deps.★
pip hash dist/pkg.whl
Compute the hash to paste into the file.

09Lock & Reproducepylock.toml · PEP 751

pip lock -e .
Emit pylock.toml — a real, resolved, hashed lockfile. Experimental.★
pip lock -r req.txt -o pylock.toml
Lock from an existing requirements file.
pip install -r pylock.toml
Install from the lock. Valid for this Python and platform only.
pip install --require-hashes -r req.txt
Refuse anything unhashed. The deployment safety net.★
pip download -r req.txt -d ./wheels
Fetch without installing — build an offline bundle.
pip wheel -r req.txt -w ./wheels
Build every dependency to a wheel once, then install from the dir anywhere.

10Uninstall & Cachereclaiming space

pip uninstall requests
Removes the package — not its dependencies. They linger as orphans.leaves orphans
pip uninstall -y -r requirements.txt
Bulk removal, no prompts.destructive
pip cache info
Size and location of both caches.
pip cache list numpy
Which wheels are cached for a package.
pip cache remove numpy
Surgical. The fix when a bad cached wheel keeps coming back.
pip cache purge
Nuke both caches. Safe — just costs you re-downloads.
pip install --no-cache-dir x
Only in container builds that cache a layer above. Otherwise it just makes pip slow.

11Wheels vs Sourcewhen a build goes wrong

pip install --only-binary=:all: x
Never compile. Fails loudly instead of silently spending 10 minutes on a C build.★
pip install --no-binary=:all: x
Force a build from sdist — e.g. to pick up local CPU optimizations.
pip install --prefer-binary x
Take an older wheel over a newer sdist.
pip install --no-build-isolation x
Build against the current env instead of a clean one. Build deps must already be present.
pip debug
Shows the compatible wheel tags for this interpreter — the answer to "why is there no wheel for me".

12When the Resolver Fightsbacktracking & conflicts

pip install tea "cup>=3.13"
Add a lower bound on whatever it's backtracking on. Shrinks the search space dramatically.★
pip install -c constraints.txt tea
Same idea, for transitive deps you can't name on the CLI.
pip install -U pkg-a pkg-b
Fixes ResolutionTooDeep: ignore what's installed and resolve fresh.
# loosen the pins
ResolutionImpossible usually means you over-pinned. Drop == to >= and let pip find the overlap.★
pip install --force-reinstall x
Reinstall even if satisfied. A blunt fix for a corrupted install.

13Config & Env Varsset it once

pip config set global.index-url URL
Persist a private index instead of retyping -i.
pip config set global.require-virtualenv true
Refuse to install outside a venv. The best guardrail pip offers.★
export PIP_REQUIRE_VIRTUALENV=1
Every flag has a PIP_* env var. Underscores or dashes both work.
export PIP_CONSTRAINT=constraints.txt
Applies constraints to every pip run — including builds. Handy in CI.
pip config debug
Which file won, and why.

★Choosing the Targetwhere does it land?

(nothing)
The active environment. If no venv is active, that's your system Python — the source of most pip disasters.★
--user
~/.local/…. Blocked on PEP 668 systems. Prefer a venv.
--target ./libs
Dump packages into a plain directory — AWS Lambda bundles, vendoring.
--prefix /opt/app
Install into a custom prefix tree.
--python .venv/bin/python
Explicitly name the interpreter to act on.

pip cheat sheet

The things that actually confuse people

What `pip install` really does

Backtracking, illustrated

Anatomy of a requirement

What `~=` actually means

`externally-managed-environment`

Four files, four jobs

Three rungs of "reproducible"

Worth memorizing