ModuleNotFoundError: No Module Named ‘pkg_resources’ — Why It Happens and How to Fix It

Laptop screen showing a code editor with Python programming code in a dim room

You run a script or install a package and Python stops with this message:

ModuleNotFoundError: No module named 'pkg_resources'

If this started happening recently on a project that used to work, you are not alone. In early 2026 the Python packaging tool setuptools released version 82.0.0, and that version removed the long-deprecated pkg_resources module. Projects, build scripts and old libraries that still import it suddenly broke on fresh installs.

This guide explains what pkg_resources was, why the error appears, how to fix it quickly, and how to fix it properly so it never returns. Pick the section that matches your situation: you are a user who just wants a program to run, a developer who maintains the failing code, or someone whose package fails while building.

What Is pkg_resources?

pkg_resources used to ship with setuptools. It provided runtime features for finding, inspecting and loading installed Python distributions: looking up a package’s version, reading its entry points, finding data files inside a package and parsing version strings. Many older projects import it directly, and many setup.py files import it too.

For years the setuptools documentation has told developers to migrate away from it. A Fedora change proposal notes that the module had been deprecated since April 2021. Setuptools finally removed it in version 82.0.0. The official documentation now states that pkg_resources is no longer maintained, no longer used internally by setuptools and no longer included in distributions as of v82.0.0.

Why You Are Seeing the Error

The error usually appears for one of these reasons:

  1. You have setuptools 82 or newer installed (or pulled in by a build), and the code you run still imports pkg_resources. This is the most common cause since early 2026. Reports from many projects, including Linux distributions, hosting platforms and open-source tools, describe the same breakage after the update.
  2. A package builds from source in an isolated environment. When pip builds a package, it creates a temporary environment and installs the newest setuptools unless the project pins a version. If the package’s setup.py imports pkg_resources, the build fails with this error even if your own environment has an older setuptools. One issue report described exactly this for a package whose build configuration allowed any setuptools version above 77.0.3.
  3. Setuptools is not installed at all. Newer Python versions and fresh virtual environments no longer always include setuptools. Older forum answers say that simply running pip install setuptools fixes the error, which was correct when the problem was a missing install, but it is not enough now because the latest setuptools does not contain the module.
  4. A split system package. On some Linux distributions, pkg_resources is packaged separately from setuptools, and a partial install produces confusing missing-dependency errors.

First, Check What You Have

Run these commands in the same environment where the error occurs:

python --version
python -m pip --version
python -m pip show setuptools
python -c "import pkg_resources; print(pkg_resources.__file__)"

If pip show setuptools reports version 82.0.0 or higher, or says the package is not found, you have identified the likely cause.

Quick Fix 1: Pin Setuptools to a Version That Still Has pkg_resources

The fastest solution is to install a setuptools release from before the removal. Several projects and write-ups recommend pinning to a version below 82, for example the last 80.x release.

python -m pip install "setuptools<82"

One write-up suggests pinning to 80.10.2 or lower as a practical temporary fix, and the OpenStack project pinned its development tooling to below 82.0.0 for stable branches. Use the same approach in a requirements file:

setuptools<82

This is a stopgap. It keeps old code running but does not fix the underlying dependency on a deprecated module. Treat it as a way to get unblocked while you or the maintainers update the code.

Quick Fix 2: Update the Package That Imports pkg_resources

If the error comes from a third-party library, check whether a newer release exists. Many projects have already published fixes. A hosting-platform troubleshooting page, for example, says that the affected apps had newer releases that no longer import pkg_resources, and calls upgrading the real fix.

python -m pip install --upgrade the-package-name

If the project has no fix yet, search its issue tracker. Maintainers often link a pull request that replaces pkg_resources with the standard library. You can also open an issue or submit a patch.

Quick Fix 3: Fix Build Failures During pip install

If the error appears while pip is building a wheel from source, the problem lives in the temporary build environment, not your normal environment. You have several options:

Option A: Use a constraints file for build isolation

Create a file called constraints.txt:

setuptools<82

Then run:

PIP_CONSTRAINT=constraints.txt python -m pip install the-package

Many people use this approach to force an older setuptools into isolated build environments. Test it in your setup, since behaviour can differ between pip versions.

Option B: Disable build isolation

Install the build requirements yourself in your environment, then ask pip not to create a separate one:

python -m pip install "setuptools<82" wheel
python -m pip install --no-build-isolation the-package

This uses whatever setuptools is already installed. It also means you take responsibility for installing every build dependency the package needs.

Option C: If you maintain the package, cap the build requirement

In pyproject.toml:

[build-system]
requires = ["setuptools>=77.0.3,<82"]
build-backend = "setuptools.build_meta"

This is a short-term patch. The better fix is removing the pkg_resources import, covered below.

Quick Fix 4: Use a Backport Only as a Last Resort

A third-party PyPI package called pkg-resources-backport advertises itself as a snapshot of the last pkg_resources module from setuptools, for situations where runtime dependencies require it and you cannot downgrade to setuptools 80.10.x. Third-party packages carry their own trust and maintenance risks, so review the project before installing it, and do not use it in sensitive production systems without checking. Fedora’s plan also mentions a compatibility package for distribution users who need pkg_resources temporarily.

The Permanent Fix: Migrate Away From pkg_resources

If you control the code, replace pkg_resources with standard-library modules. The setuptools documentation recommends these replacements:

  • Resource access: use importlib.resources (or the backport importlib_resources).
  • Distribution metadata and entry points: use importlib.metadata (or the backport importlib_metadata).
  • Requirement and version parsing: use the packaging library.

Common conversions

Getting a package version

# Old
from pkg_resources import get_distribution, DistributionNotFound
try:
    version = get_distribution("mypackage").version
except DistributionNotFound:
    version = "unknown"

# New
from importlib.metadata import version, PackageNotFoundError
try:
    pkg_version = version("mypackage")
except PackageNotFoundError:
    pkg_version = "unknown"

This is the same replacement used in a pull request that fixed the vpython package for setuptools 82: get_distribution(name).version becomes version(name), and DistributionNotFound becomes PackageNotFoundError.

Parsing versions

# Old
from pkg_resources import parse_version

# New
from packaging.version import parse as parse_version

Add packaging to your dependencies. Do not import it from inside setuptools’ private _vendor folder. A reviewer on one project pointed out that the vendor namespace is an internal implementation detail that should not be relied upon.

Entry points and plugins

# Old
import pkg_resources
for ep in pkg_resources.iter_entry_points("myapp.plugins"):
    plugin = ep.load()

# New (Python 3.10+)
from importlib.metadata import entry_points
for ep in entry_points(group="myapp.plugins"):
    plugin = ep.load()

On older Python versions the entry_points() API differs, so use the importlib_metadata backport for consistent behaviour.

Reading data files inside a package

# Old
import pkg_resources
path = pkg_resources.resource_filename("mypackage", "data/config.json")

# New
from importlib.resources import files
path = files("mypackage").joinpath("data/config.json")
text = path.read_text()

Use as_file() from the same module if you need a real filesystem path for a resource inside a zip.

Namespace packages

Old code such as __import__('pkg_resources').declare_namespace(__name__) in an __init__.py is a harder case. A discussion on the OpenStack mailing list noted that declaring namespace packages with pkg_resources cannot be directly replaced by importlib. The usual solution is to move to native (implicit) namespace packages, which means removing the __init__.py from the namespace directory and configuring packaging accordingly. Test this carefully, because it changes how the package is laid out.

Setup scripts

If setup.py imports pkg_resources only to compare versions or read a file, replace those lines with packaging or plain Python. A fix merged in one project also removed an unused distutils import, since distutils was removed from the standard library in Python 3.12.

Special Situations

Virtual environments

Activate the environment, then run python -m pip so you modify the right interpreter. If the environment is disposable, recreate it with a pinned setuptools in the requirements file.

Docker and CI pipelines

Fresh builds always pull the newest setuptools, which is why a pipeline can break without any code change. Pin versions in your Dockerfile or constraints file and rebuild. OpenStack’s DevStack, for instance, pinned setuptools below 82.0.0 on stable branches.

Linux system Python

Avoid changing the system Python’s packages with sudo pip, which can break your operating system’s tools. Use a virtual environment, or the distribution’s package manager. Fedora has described compatibility packages and alternative setuptools packages for systems that need an older version.

Machine-learning and data projects

Many projects in this area depend on older tools. If a repository’s instructions say to run pip install -r requirements.txt and it fails, add the constraint setuptools<82 or use the Python and package versions the project recommends.

A Quick Decision Guide

Situation Best first step
You only use a program and it crashes Upgrade the program; otherwise install setuptools<82
pip fails while building a package Use PIP_CONSTRAINT or --no-build-isolation
You maintain the code Replace pkg_resources with importlib and packaging
CI suddenly breaks Pin setuptools in the pipeline, then plan the migration
You cannot change the code or the version Consider a vetted backport, and document the risk

How to Prevent It Next Time

  • Pin build dependencies and use lock files so a new release does not break a working build overnight.
  • Run tests in CI against the latest setuptools to catch breakage early.
  • Search your code for pkg_resources and declare_namespace.
  • Prefer standard-library APIs where they exist.
  • Read release notes for build tools before upgrading.

Frequently Asked Questions

Why did this error start suddenly?

Setuptools 82.0.0 removed the module, and new installs and rebuilds pick up that version unless it is pinned.

Will pip install setuptools fix it?

Only if setuptools was missing and the version you install still contains the module. With the latest versions, you need to install an older release such as setuptools<82 or update the code.

Is it safe to downgrade setuptools?

For many projects it is a reasonable temporary measure, but older versions may lack newer features and fixes. Plan to migrate.

Which Python versions are affected?

The cause is the setuptools version, not the Python version, although newer Python versions are more likely to start with a fresh environment that lacks older setuptools.

Can I import pkg_resources from somewhere else?

Not from the official setuptools 82 or later. Use importlib alternatives, an older setuptools or a trusted compatibility package.

Final Thoughts

The No module named 'pkg_resources' error is a symptom of a long-announced change finally taking effect. If you need things working in the next five minutes, pin setuptools<82 in the environment, the constraints file or the build configuration. If you own the code, spend the time to migrate to importlib.metadata, importlib.resources and packaging, so a future setuptools update cannot break your project again.

Note: Version numbers and package behaviour change quickly. Check the official setuptools documentation and your package’s release notes for current guidance, and test fixes in a disposable environment first.

2 thoughts on “ModuleNotFoundError: No Module Named ‘pkg_resources’ — Why It Happens and How to Fix It”

  1. Hello There. I found your blog using msn. This is a very well written article.

    I will make sure to bookmark it and return to read more
    of your useful information. Thanks for the post. I’ll definitely comeback.

Leave a Comment

Your email address will not be published. Required fields are marked *

Scroll to Top