pypa/pip · error · DistributionNotFound

The '{self.req}' distribution was not found and is required

Error message

The '{self.req}' distribution was not found and is required by {self.requirers_str}

What it means

Raised as DistributionNotFound during WorkingSet.resolve() when a required distribution cannot be found in the working set, the search environment, or via the installer. The message lists the requirement and the requirers (the packages/applications that need it). This means the dependency is simply not installed and cannot be located.

Source

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

            # Find the best distribution and add it to the map
            dist = self.by_key.get(req.key)
            if dist is None or (dist not in req and replace_conflicting):
                ws = self
                if env is None:
                    if dist is None:
                        env = Environment(self.entries)
                    else:
                        # Use an empty environment and workingset to avoid
                        # any further conflicts with the conflicting
                        # distribution
                        env = Environment([])
                        ws = WorkingSet([])
                dist = best[req.key] = env.best_match(
                    req, ws, installer, replace_conflicting=replace_conflicting
                )
                if dist is None:
                    requirers = required_by.get(req, None)
                    raise DistributionNotFound(req, requirers)
            to_activate.append(dist)
        if dist not in req:
            # Oops, the "best" so far conflicts with a dependency
            dependent_req = required_by[req]
            raise VersionConflict(dist, req).with_context(dependent_req)
        return dist

    @overload
    def find_plugins(
        self,
        plugin_env: Environment,
        full_env: Environment | None,
        installer: _InstallerTypeT[_DistributionT],
        fallback: bool = True,
    ) -> tuple[list[_DistributionT], dict[Distribution, Exception]]: ...
    @overload
    def find_plugins(
        self,

View on GitHub (pinned to f399c37189)

Solutions

1. Install the missing package: pip install <package-name>.
2. Correct any typo in the requirement string.
3. Ensure the package is listed in your install_requires/dependencies and that the install step ran successfully.

Example fix

// before
pkg_resources.require('CustomePkg>=1.0')  # typo, not installed
// after
pip install CustomPkg
pkg_resources.require('CustomPkg>=1.0')

# Check existence before resolving
import importlib.util
if importlib.util.find_spec(pkg_name) is None:
    raise ImportError(f'{pkg_name} is not installed')

try:
    pkg_resources.require(req_str)
except DistributionNotFound as e:
    print(e.report())
    # offer to install e.req.project_name

When it happens

Trigger: Calling pkg_resources.require('nonexistent-package==1.0') or working_set.resolve([...]) for a dependency that is not installed and not installable by the configured installer.

Common situations: A missing dependency that was never installed; a typo in a package name in requirements.txt; a dependency that is optional but required at runtime; an installer (e.g. in a frozen/offline env) that cannot fetch the package.

Related errors

• Error decoding metadata for {self._wheel_name}: {e} in {name
• Wheel '{name}' located at {location} is invalid.
• {name} has an invalid wheel, {e}
• None {metadata_name} metadata found for distribution: {dist}
• Error parsing entry points for {self.raw_name}: {e}

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