Added in version 6.0.
pip provides an on-by-default caching, designed to reduce the amount of timespent on duplicate downloads and builds.
What is cached¶
HTTP responses¶
This cache functions like a web browser cache.
When making any HTTP request, pip will first check its local cache to determineif it has a suitable response stored for that request which has not expired. Ifit does then it returns that response and doesn’t re-download the content.
If it has a response stored but it has expired, then it will attempt to make aconditional request to refresh the cache which will either return an emptyresponse telling pip to simply use the cached item (and refresh the expirationtimer) or it will return a whole new response which pip can then store in thecache.
While this cache attempts to minimize network activity, it does not preventnetwork access altogether. If you want a local install solution thatcircumvents accessing PyPI, see Installing from local packages.
Changed in version 23.3: A new cache format is now used, stored in a directory called http-v2 (seebelow for this directory’s location). Previously this cache was stored in adirectory called http in the main cache directory. If you have completelyswitched to newer versions of pip, you may wish to delete the old directory.
Locally built wheels¶
pip attempts to use wheels from its local wheel cache whenever possible.
This means that if there is a cached wheel for the same version of a specificpackage name, pip will use that wheel instead of rebuilding the project.
When no wheels are found for a source distribution, pip will attempt to build awheel using the package’s build system. If the build is successful, this wheelis added to the cache and used in subsequent installs for the same packageversion.
Wheels built from source distributions provided to pip as a direct path (suchas pip install .) are not cached across runs, though they may be reused withinthe same pip execution.
Changed in version 20.0: pip now caches wheels when building from an immutable Git reference(i.e. a commit hash).
Where is the cache stored¶
Caution
The exact filesystem structure of pip’s cache’s contents is considered to bean implementation detail and may change between any two versions of pip.
pip cache dir¶
Added in version 20.1.
You can use pip cache dir to get the cache directory that pip is currently configured to use.
Default paths¶
~/.cache/pip
pip will also respect XDG_CACHE_HOME.
~/Library/Caches/pip
%LocalAppData%\pip\Cache
Avoiding caching¶
pip tries to use its cache whenever possible, and it is designed do the rightthing by default.
In some cases, pip’s caching behaviour can be undesirable. As an example, if youhave package with optional C extensions, that generates a pure Python wheelwhen the C extension can’t be built, pip will use that cached wheel even whenyou later invoke it from an environment that could have built those optional Cextensions. This is because pip is seeing a cached wheel that matches thepackage being built, and pip assumes that the result of building a package froma package index is deterministic.
The recommended approach for dealing with these situations is to directlyinstall from a source distribution instead of letting pip auto-discover thepackage when it is trying to install. Installing directly from a sourcedistribution will make pip build a wheel, regardless of whether there is amatching cached wheel. This usually means doing something like:
$ python -m pip download sampleproject==1.0.0 --no-binary :all:$ python -m pip install sampleproject-1.0.0.tar.gz
$ python -m pip download sampleproject==1.0.0 --no-binary :all:$ python -m pip install sampleproject-1.0.0.tar.gz
C:> py -m pip download sampleproject==1.0.0 --no-binary :all:C:> py -m pip install sampleproject-1.0.0.tar.gz
It is also a good idea to remove the offending cached wheel using thepip cache command.
Cache management¶
The pip cache command can be used to manage pip’s cache.
General overview¶
pip cache info provides an overview of the contents of pip’s cache, such as the total size and location of various parts of it.
Removing a single package¶
pip cache remove setuptools removes all wheel files related to setuptools from pip’s cache. HTTP cache files are not removed at this time.
Removing the cache¶
pip cache purge will clear all files from pip’s wheel and HTTP caches.
Listing cached files¶
pip cache list will list all wheel files from pip’s cache.
pip cache list setuptools will list all setuptools-related wheel files from pip’s cache.
Disabling caching¶
pip’s caching behaviour is disabled by passing the --no-cache-dir option.
It is, however, recommended to NOT disable pip’s caching unless you have caching at a higher level (eg: layered caches in container builds). Doing so cansignificantly slow down pip (due to repeated operations and package builds)and result in significantly more network usage.
