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 you attempt to change the cache extraction directory after resources have already been extracted during the current process. The manager caches extracted files under self.cached_files; once that set is non-empty, moving the base path would orphan already-extracted files, so it refuses. You must call cleanup_resources() first to clear the cache before repointing the path.

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 d7d0d0a394)

Solutions

1. Call pkg_resources.cleanup_resources() before set_extraction_path() to clear cached_files and allow the change.
2. Set the extraction path once at process startup, before any resource access that would trigger extraction.
3. If you need multiple extraction roots, instantiate a fresh ResourceManager rather than reusing the module-level one.

Example fix

// before
pkg_resources.resource_filename('pkg', 'data.bin')  # triggers extraction
pkg_resources.set_extraction_path('/new/cache')        # ValueError

// after
pkg_resources.cleanup_resources()
pkg_resources.set_extraction_path('/new/cache')

import pkg_resources

def safe_set_extraction_path(new_path):
    mgr = pkg_resources._namespace_handlers  # not the manager; use the global fn
    # the global resource manager tracks cached_files
    import pkg_resources as pr
    rm = pr.__dict__.get('_manager')
    if rm is not None and getattr(rm, 'cached_files', None):
        pr.cleanup_resources()
    pr.set_extraction_path(new_path)

# state guard: check the manager's cache before repointing
import pkg_resources

def extraction_path_changeable():
    rm = getattr(pkg_resources, '_resource_manager', None)
    return not (rm and getattr(rm, 'cached_files', None))

try:
    pkg_resources.set_extraction_path(new_path)
except ValueError as e:
    if 'already extracted' in str(e):
        pkg_resources.cleanup_resources()
        pkg_resources.set_extraction_path(new_path)
    else:
        raise

When it happens

Trigger: Calling pkg_resources.set_extraction_path(new_dir) after any earlier call to resource_filename() / get_resource_filename() on a zip/egg-backed provider caused extraction into the old directory.

Common situations: Setting a custom extraction path late in a long-running process, after plugins or dependencies already triggered extraction from the default temp location. Also in test harnesses that reconfigure the extraction path between tests without resetting state.

Related errors

• resource_filename() only supported for .egg, not .zip
• "os.rename" and "os.unlink" are not supported on this platfo
• "egg_name" is empty. This likely means no egg could be found
• Error decoding metadata for {self._wheel_name}: {e} in {name
• Wheel '{name}' located at {location} is invalid.

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