How can I manually validate pip:CACHE_DESERIALIZATION_FAILED?

Check your disk for errors and free space (cache corruption can be a symptom). Check where pip cache is stored: `python -m pip cache dir`.

Cache entry deserialization failed, entry ignored

Q: How do I prevent pip:CACHE_DESERIALIZATION_FAILED in CI?

Avoid killing pip mid-install in CI (allow it to finish writing caches). Ensure adequate disk space for pip cache/temp directories. Pin pip versions in CI if cache format changes cause issues.

What Is Wrong With the Local Cache

pip detected a corrupted or incompatible cache entry and ignored it. Installs may be slower or may fail if corruption is widespread.

The upstream service may be fine. This is usually about bad local cache state getting in the way of an otherwise normal install or download.

Clear the corrupted cache entry

Clear cache:python -m pip cache purge

Retry with --no-cache-dir to bypass caching temporarily.

If the issue recurs, ensure you have enough disk space and check filesystem health.

Why the Cache State Is Bad

Usually this comes down to a prior pip run was interrupted while writing cache entries, disk issues (full disk, filesystem errors) corrupted cached files, or cache format changed across pip versions and old entries are no longer readable.

Verify the Cache Path Is Healthy Again

Re-run the install and confirm cache warnings are gone (or reduced), and confirm installs succeed and are stable across retries.

Manual cache cleanup

Check your disk for errors and free space (cache corruption can be a symptom), and check where pip cache is stored with python -m pip cache dir.

Examples

Cache entry deserialization failed, entry ignored

What pip caches

pip caches downloaded artifacts and some metadata to speed up future installs. If the cache is corrupted (due to interrupted writes, disk issues, or format changes), pip may warn and ignore entries. Inconsistent caches can also contribute to confusing network/download errors.

Prevent It From Coming Back

To prevent this, avoid killing pip mid-install in CI (allow it to finish writing caches), ensure adequate disk space for pip cache/temp directories, and pin pip versions in CI if cache format changes cause issues.

Docs and source code

github.com/pypa/pip/blob/25.3/src/pip/_vendor/cachecontrol/controller.py

pip (via its vendored CacheControl) emits this warning when a cached response cannot be deserialized and is ignored. - GitHub

    def _load_from_cache(self, request: PreparedRequest) -> HTTPResponse | None:
        """
        Load a cached response, or return None if it's not available.
        """
        # We do not support caching of partial content: so if the request contains a
        # Range header then we don't want to load anything from the cache.
        if "Range" in request.headers:
            return None

        cache_url = request.url
        assert cache_url is not None
        cache_data = self.cache.get(cache_url)
        if cache_data is None:
            logger.debug("No cache entry available")
            return None

        if isinstance(self.cache, SeparateBodyBaseCache):
            body_file = self.cache.get_body(cache_url)
        else:
            body_file = None

        result = self.serializer.loads(request, cache_data, body_file)
        if result is None:
            logger.warning("Cache entry deserialization failed, entry ignored")
        return result