Skip to content

ModuleNotFoundError: No Module Named ‘pkg_resources’ – How to Fix It

Close-up of a laptop screen displaying code against a dark background with blue lighting

The error ModuleNotFoundError: No module named 'pkg_resources' means the Python interpreter you are running cannot find setuptools, the package that provides pkg_resources. In most cases the fix is to install or upgrade setuptools in that same interpreter:

python -m pip install --upgrade setuptools

Using python -m pip matters. It guarantees pip installs into the exact Python that is raising the error, rather than a different installation on your machine.

The rest of this guide explains why the module goes missing, covers the fixes for virtual environments, Linux system Python and failing builds, and shows how to stop depending on pkg_resources in your own code.

Why This Error Happens

pkg_resources is not a standalone package. It ships inside setuptools. If setuptools is missing from the environment, any code that does import pkg_resources fails. Several things cause that:

  • Newer virtual environments. Python 3.12 stopped installing setuptools by default in new venvs, so older scripts that expected it now break.
  • A broken or partial setuptools install, often after a failed upgrade.
  • Using a different Python than you think. Pip installed setuptools for one interpreter and your script runs another.
  • Minimal system Pythons. Some Linux distributions split setuptools into a separate package.
  • Newer setuptools releases that have deprecated or changed pkg_resources, which affects older tools that still import it.

Step 1: Confirm Which Python Is Failing

Run these commands in the same terminal where the error appears:

python --version
python -c "import sys; print(sys.executable)"
python -m pip --version

Check that the pip path and the Python path point to the same environment. If they differ, that mismatch is your real problem.

Fix 1: Install or Upgrade setuptools

python -m pip install --upgrade pip setuptools wheel

Then test it:

python -c "import pkg_resources; print('ok')"

If it prints ok, you are done.

Fix 2: Reinstall a Broken setuptools

python -m pip install --force-reinstall setuptools

If pip itself fails, you can bootstrap it with python -m ensurepip --upgrade and then repeat the install.

Fix 3: Recreate the Virtual Environment

If a venv is old or damaged, rebuilding is often quicker than debugging it:

deactivate
rm -rf .venv
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip setuptools wheel
python -m pip install -r requirements.txt

On Windows, activate with .venv\Scripts\activate.

Fix 4: Debian and Ubuntu System Python

On Debian-based systems, install the packaged version instead of forcing pip into the system environment:

sudo apt update
sudo apt install python3-setuptools python3-pkg-resources

Avoid using sudo pip on a system Python, because it can clash with the operating system’s own packages. A virtual environment is safer.

Fix 5: Build Errors While Installing a Package

Sometimes the error appears while pip builds a package from source, inside an isolated build environment. Two options are commonly suggested:

python -m pip install --no-build-isolation package-name

This uses the setuptools already in your environment. Alternatively, if a legacy package breaks with the newest setuptools, a temporary version pin such as setuptools<81 can get you unblocked. Treat that as a short-term workaround and look for an updated release of the package.

Quick Comparison of the Fixes

Situation Best fix
New Python 3.12 venv Install setuptools in the venv
Pip and Python mismatch Use python -m pip
Corrupt install Force reinstall or rebuild the venv
Debian or Ubuntu system Python Install python3-setuptools through apt
Failure during a package build Try --no-build-isolation or pin setuptools

For Developers: Stop Importing pkg_resources

The official setuptools documentation describes pkg_resources as legacy and recommends newer standard-library tools. If the import is in your own code, replace it:

  • Use importlib.metadata to read installed package versions and entry points.
  • Use importlib.resources to access data files bundled inside packages.
  • Use the packaging library for version parsing and comparisons.

A typical swap looks like this:

# Old
import pkg_resources
version = pkg_resources.get_distribution("requests").version

# New
from importlib.metadata import version
v = version("requests")

Read the importlib.metadata documentation and the setuptools pkg_resources notes for the full details.

Keep Your Tooling Tidy

Dependency problems like this one are easier to avoid with isolated environments and pinned requirements. If you enjoy digging into developer tools and web projects, you may also like our pieces on web tools and platforms and the Shortengine platform overview.

Frequently Asked Questions

What is pkg_resources in Python?

It is a module that comes with setuptools. Older code used it to find installed packages, read versions and load bundled resources. It is now considered legacy in favour of importlib tools.

How do I install pkg_resources with pip?

You do not install it directly. Install setuptools with python -m pip install --upgrade setuptools, and pkg_resources comes with it.

Why did this start after I moved to Python 3.12?

Python 3.12 virtual environments no longer include setuptools by default. Scripts or build tools that assumed it was always present now need it installed explicitly.

Why does pip say setuptools is installed but the error remains?

You are probably using a different interpreter than the one pip installed into. Run python -m pip show setuptools with the failing Python to check, and install it with that same command.

Is it safe to pin setuptools to an older version?

It is a reasonable temporary workaround for legacy packages, but it can leave you without newer fixes. Prefer updating the package that imports pkg_resources when a newer release exists.

What should I use instead of pkg_resources?

Use importlib.metadata for versions and entry points, importlib.resources for package data and packaging for version handling.

Conclusion

This error almost always means setuptools is missing from the interpreter you are running. Install it with python -m pip install --upgrade setuptools, confirm pip and Python match, and rebuild a damaged venv if needed. For long-term stability, move your own code to importlib.metadata and importlib.resources.