Wheels & Caching

This content was generated with the assistance of AI and should be verified against the official documentation before being relied on in production.

The reference material consulted while preparing these pages is listed in the Python Reference bibliography.

pip builds wheels whenever it has to install from source, and keeps both downloaded files and the wheels it built in a cache. This page covers the pip wheel command, wheelhouses for offline installs, and the cache, for pip 26.2.2. The examples ran on CPython 3.14.6 on 2026-10-22 with PIP_CACHE_DIR pointing at an empty scratch directory (shown as …/wc/cache) so that the cache contents are only what these commands put there.

pip wheel

pip wheel resolves like pip install but, instead of installing, writes a wheel for every requirement and dependency into a directory: wheels that already exist are copied as they are, sdists are built. docopt (sdist only) gets built, the rest are downloaded:

python -m pip wheel -w wheelhouse --find-links ./dist "birdtally[pretty]" docopt
ls wheelhouse
Saved ./wheelhouse/birdtally-0.1.0-py3-none-any.whl
Saved ./wheelhouse/rich-15.0.0-py3-none-any.whl
Saved ./wheelhouse/pygments-2.21.0-py3-none-any.whl
Saved ./wheelhouse/markdown_it_py-4.2.0-py3-none-any.whl
Saved ./wheelhouse/mdurl-0.1.2-py3-none-any.whl
  Building wheel for docopt (pyproject.toml): started
  Building wheel for docopt (pyproject.toml): finished with status 'done'
  Created wheel for docopt: filename=docopt-0.6.2-py2.py3-none-any.whl size=13781 sha256=5a0188f9edd4ea8623956292f0c308b9265ec6f9e1e50efa160e208abedb978b
  Stored in directory: …/wc/cache/wheels/79/6f/5f/26c3d1a144117ef52122d67c32b9f3c297c3dec4fea00a31ac
Successfully built docopt
birdtally-0.1.0-py3-none-any.whl
docopt-0.6.2-py2.py3-none-any.whl
markdown_it_py-4.2.0-py3-none-any.whl
mdurl-0.1.2-py3-none-any.whl
pygments-2.21.0-py3-none-any.whl
rich-15.0.0-py3-none-any.whl

  • -w/--wheel-dir <dir> (PIP_WHEEL_DIR) is the output directory, the current directory by default.

  • --no-deps builds only the named requirements, which for a single project is the same as python -m build --wheel.

  • --no-verify (PIP_NO_VERIFY) skips the check that a built wheel is valid.

  • Most pip install options apply: index options, -r, -c, --build-constraint, -C, --no-build-isolation, --only-binary. Since 26.2 a copy failure is reported as such instead of as a misleading build failure.

Differences to build. python -m build builds both an sdist and a wheel of one project with any PEP 517 backend; it is the tool to make your release files (see Building sdists & Wheels). pip wheel cannot make sdists at all, which is deliberate ("building a source distribution is never needed when installing"), but it resolves and builds a whole dependency tree, which build does not.

Source: pip wheel: differences to build, pip wheel: --wheel-dir, pip wheel: --no-verify.

Wheelhouses and offline installs

A directory of wheels is a wheelhouse. Built once on a machine with network access (and the compilers sdists need), it can be installed on a machine with neither:

python -m pip install --no-index --find-links wheelhouse "birdtally[pretty]"

The output of that command is on Package Indexes & Finding Packages. The pip documentation recommends combining wheelhouses with a hashed requirements file, so that the bundle is also verified; see Repeatable & Secure Installs.

Source: pip user guide: Installing from wheels, pip: Using a wheelhouse (installation bundles).

What pip caches

Cache Contents Notes

HTTP cache (http-v2/)

Index pages and downloaded files (wheels, sdists, PEP 658 metadata files).

http-v2 since pip 23.3 (older pips used http/). Since 26.2 index pages follow the server’s Cache-Control header instead of being revalidated on every request; use --refresh-package <name> (or :all:) when you need a release published moments ago.

Locally built wheels (wheels/)

Wheels pip built from sdists it downloaded.

Reused for the same sdist next time. Not used for pip install . of a local directory (never since 26.2), nor for editable installs. With hash checking, an origin.json next to the wheel (since 23.1) records which sdist it came from.

After the pip wheel run above, the next install of docopt uses the cached wheel and does not build again:

python -m pip install docopt
Collecting docopt
  Using cached docopt-0.6.2-py2.py3-none-any.whl
Installing collected packages: docopt
Successfully installed docopt-0.6.2

The cache assumes a build is deterministic. A package whose sdist builds a pure-Python wheel when a compiler is missing will keep being installed from that fallback wheel later, even where the C extension could have been built; install it with --no-cache-dir or --no-binary <name> once, or remove it from the cache.

Source: pip: What is cached, pip: HTTP responses, pip: Locally built wheels, pip: Avoiding caching.

Where the cache lives

Platform Default Override

Linux

~/.cache/pip

XDG_CACHE_HOME (then $XDG_CACHE_HOME/pip)

macOS

~/Library/Caches/pip

XDG_CACHE_HOME too, since pip 26.2

Windows

%LocalAppData%\pip\Cache

any

--cache-dir <dir> or PIP_CACHE_DIR

The macOS change comes from platformdirs 4.6, which pip 26.2 vendors; it also moves the global and user configuration files when XDG_DATA_DIRS/XDG_DATA_HOME are set.

Source: pip: Where is the cache stored, pip: Default paths.

pip cache

python -m pip cache info
python -m pip cache list
python -m pip cache list --format=abspath
Package index page cache location (pip v23.3+): …/wc/cache/http-v2
Package index page cache location (older pips): …/wc/cache/http
Package index page cache size: 3.0 MB
Number of HTTP files: 36
Locally built wheels location: …/wc/cache/wheels
Locally built wheels size: 14 kB
Number of locally built wheels: 1
Cache contents:

 - docopt-0.6.2-py2.py3-none-any.whl (13 kB)
…/wc/cache/wheels/79/6f/5f/26c3d1a144117ef52122d67c32b9f3c297c3dec4fea00a31ac/docopt-0.6.2-py2.py3-none-any.whl

  • pip cache dir prints the cache directory.

  • pip cache list [<pattern>] lists only the locally built wheels; --format human|abspath chooses the output.

  • pip cache remove <pattern> deletes the matching cached wheels; a pattern that matches nothing prints a warning but exits with 0.

  • pip cache purge deletes everything, the HTTP cache included; since 26.2 it also removes the empty http-v2 directories.

python -m pip cache remove docopt
python -m pip cache purge
Files removed: 1 (13 kB)
Directories removed: 5
Files removed: 36 (3.0 MB)
Directories removed: 83

Source: pip: Cache management, pip: Removing a single package, pip: Removing the cache, pip: Listing cached files, pip cache.

Disabling the cache

--no-cache-dir (PIP_NO_CACHE_DIR=1) disables both caches for one command. The documentation does not recommend it in general, because the cache makes repeated installs much faster and is safe. Its right place is a container image build, where a cache in a layer only makes the image bigger; in CI, persist the cache directory between jobs instead (see CI Caching & Containers). In a configuration file the option is a "negative" boolean: no-cache-dir = false enables it, a documented quirk explained on pip: Configuration.

Source: pip: Disabling caching.

pip and Poetry

pip Poetry

pip wheel --no-deps .

poetry build -f wheel

pip cache dir

poetry config cache-dir

pip cache list

poetry cache list (lists the per-source caches)

pip cache purge

poetry cache clear --all <source>

--no-cache-dir

--no-cache (global option)

References