pypa/pip · error · ValueError

Can't change extraction path, files already extracted

Error message

Can't change extraction path, files already extracted

What it means

Raised by ResourceManager.set_extraction_path() when resources have already been extracted (cached_files is non-empty). Once files exist on disk under the current extraction path, the path cannot be changed because existing extracted files would be orphaned. You must call cleanup_resources() first.

Solutions

Call cleanup_resources() before set_extraction_path() to clear cached files.
Set the extraction path at process startup, before any resource extraction occurs.
Set the PYTHON_EGG_CACHE environment variable before interpreter start to avoid needing set_extraction_path() entirely.

Example fix

// before
# after extractions happened
manager.set_extraction_path(new_dir)  # raises
// after
manager.cleanup_resources()
manager.set_extraction_path(new_dir)

Defensive patterns

Strategy: validation

Validate before calling

if manager.cached_files:
    manager.cleanup_resources()
manager.set_extraction_path(new_path)

Try / catch

try:
    manager.set_extraction_path(path)
except ValueError:
    manager.cleanup_resources()
    manager.set_extraction_path(path)

Prevention

Set extraction path before any resource access.
Set PYTHON_EGG_CACHE env var at process start instead.

When it happens

Trigger: Calling set_extraction_path(new_path) after resource_filename() or another extraction has already occurred in the same ResourceManager instance.

Common situations: Calling set_extraction_path() too late in a long-running process; reconfiguring the egg cache after zip-based resources were already unpacked.

Related errors

AI-assisted analysis of pypa/pip@f399c37189 (2026-08-08). Data as JSON: /api/errors/fa53dd1f0c57a85f. Report an issue: GitHub.

Appendix: source

Thrown at src/pip/_vendor/pkg_resources/__init__.py:1507

        If you do not call this routine before any extractions take place, the
        path defaults to the return value of ``get_default_cache()``.  (Which
        is based on the ``PYTHON_EGG_CACHE`` environment variable, with various
        platform-specific fallbacks.  See that routine's documentation for more
        details.)

        Resources are extracted to subdirectories of this path based upon
        information given by the ``IResourceProvider``.  You may set this to a
        temporary directory, but then you must call ``cleanup_resources()`` to
        delete the extracted files when done.  There is no guarantee that
        ``cleanup_resources()`` will be able to remove all extracted files.

        (Note: you may not change the extraction path for a given resource
        manager once resources have been extracted, unless you first call
        ``cleanup_resources()``.)
        """
        if self.cached_files:
            raise ValueError("Can't change extraction path, files already extracted")

        self.extraction_path = path

    def cleanup_resources(self, force: bool = False) -> list[str]:
        """
        Delete all extracted resource files and directories, returning a list
        of the file and directory names that could not be successfully removed.
        This function does not have any concurrency protection, so it should
        generally only be called when the extraction path is a temporary
        directory exclusive to a single process.  This method is not
        automatically called; you must call it explicitly or register it as an
        ``atexit`` function if you wish to ensure cleanup of a temporary
        directory used for extractions.
        """
        # XXX
        return []

View on GitHub (pinned to f399c37189)