ModuleNotFoundError: No Module Named ‘pkg_resources’: Causes and Fixes

Developer typing code on a laptop with a Python book beside it in an office

The error ModuleNotFoundError: No module named ‘pkg_resources’ means the Python interpreter running your code cannot find the setuptools package, which is where pkg_resources lives. The usual fix is to install setuptools into the same environment that is running the code, with python -m pip install setuptools. On Python 3.12 and newer the error appears more often, because new virtual environments no longer include setuptools by default.

This guide explains what pkg_resources is, why the error appears, and how to fix it on Windows, macOS and Linux. It also covers virtual environments, Linux system packages, build errors during pip installs, and how to remove the dependency from your own code so it does not come back.

What Is pkg_resources?

pkg_resources is a module distributed as part of the setuptools package. Older Python tools and libraries used it to look up installed package versions, find data files and load entry points. When a program runs a line such as import pkg_resources and setuptools is missing, Python raises ModuleNotFoundError.

The error is a symptom, not a bug in Python itself. Something in your environment, or a library you installed, expects setuptools to be present and it is not.

The Quick Fix

Run this command in the same terminal, virtual environment or container where the error appears:

python -m pip install --upgrade setuptools

On macOS or Linux you may need python3 instead of python:

python3 -m pip install --upgrade setuptools

On Windows, the launcher also works:

py -m pip install --upgrade setuptools

Using python -m pip matters. It makes sure pip installs into the same interpreter that will run your script. A bare pip command may belong to a different Python installation, which is a common reason people install setuptools and still see the error.

Why Python 3.12 Triggers the Error More Often

Many reports of this error mention Python 3.12. Starting with that version, virtual environments created with the standard venv tool no longer install setuptools automatically. Projects that quietly relied on setuptools being present now fail on a fresh environment. Maintainers in several issue trackers confirm that installing setuptools makes the import error go away, and some say their own packages need updating to stop depending on pkg_resources.

That explains a typical story: your code worked yesterday on Python 3.11, you created a new environment with Python 3.12, and today the import fails.

Step-by-Step Troubleshooting

1. Check which Python is running

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

Confirm that the path points to the environment you expect. If you use a virtual environment, activate it first.

2. Check whether setuptools is installed

python -m pip show setuptools

If pip says the package is not found, install it as shown above. If it is installed but the import still fails, move to the reinstall step.

3. Reinstall setuptools

python -m pip uninstall -y setuptools
python -m pip install setuptools

A broken or partial installation can leave the folder in place without a working pkg_resources module.

4. Upgrade pip and wheel

python -m pip install --upgrade pip wheel setuptools

Old versions of pip can fail when building packages and report confusing errors.

5. Recreate a broken virtual environment

python -m venv .venv
source .venv/bin/activate        # macOS and Linux
.venv\Scripts\activate           # Windows
python -m pip install --upgrade pip setuptools
python -m pip install -r requirements.txt

If the environment was copied from another machine or created with a different Python version, rebuilding it is often faster than repairing it.

Fixes for Linux System Python

On Debian and Ubuntu systems, the operating system may manage Python packages itself. If you see the error from a system tool, a system package may be the right fix:

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

Avoid forcing pip packages into the system Python with elevated permissions. Newer distributions block this with an externally managed environment message to protect system tools. Use a virtual environment or a tool such as pipx for applications instead.

When the Error Appears During pip install

Sometimes the error shows up while pip is building a package from source, with a traceback that mentions a build environment. This happens when the package’s setup script imports pkg_resources or setuptools, and the temporary build environment lacks it. Try these in order:

  1. Upgrade pip, setuptools and wheel in your environment.
  2. Install the latest version of the package, since newer releases often remove the old dependency.
  3. Install a prebuilt wheel if one exists for your Python version.
  4. Use pip install --no-build-isolation package-name after installing setuptools yourself, if you understand the build requirements.
  5. Open an issue with the package maintainers if none of the above works.

If a Newer setuptools Breaks Your Code

pkg_resources is deprecated, and setuptools has warned that it may be removed in a future release. If a package starts failing after you upgrade setuptools, check the project’s issue tracker and the setuptools release notes. As a temporary measure you can pin an older version, for example:

python -m pip install "setuptools<81"

Treat a pin as a stopgap. The better fix is to update the library that depends on pkg_resources.

Fixing It for Good in Your Own Code

If you maintain the code that imports pkg_resources, replace it with standard library tools. They are included in Python and do not need setuptools at runtime.

Old pattern Modern replacement
pkg_resources.get_distribution(“name”).version importlib.metadata.version(“name”)
pkg_resources.resource_filename(…) importlib.resources.files(…)
pkg_resources.iter_entry_points(…) importlib.metadata.entry_points(…)

A simple example:

from importlib.metadata import version, PackageNotFoundError

try:
    print(version("requests"))
except PackageNotFoundError:
    print("Package not installed")

The Python documentation describes importlib.metadata in detail, and the setuptools project documents the pkg_resources module and its deprecation status.

Common Mistakes

  • Installing setuptools with a different pip than the interpreter that runs your script.
  • Forgetting to activate the virtual environment.
  • Using sudo pip on Linux, which can damage system packages.
  • Downloading random scripts or “fixer” tools from unknown sites to repair Python. Stick to pip, your package manager and official documentation. Our guide to staying safe online explains the risks of untrusted downloads.
  • Running outdated Docker images that predate your Python version and copying them without rebuilding.

A Quick Checklist

  1. Activate the correct environment.
  2. Run python -m pip install --upgrade setuptools.
  3. Confirm with python -c "import pkg_resources; print('ok')".
  4. If a package build fails, upgrade pip and wheel as well.
  5. Plan to update or replace libraries that still depend on pkg_resources.

If you keep your development tools patched and your downloads clean, you will meet this error less often. Our overview of antivirus and security software covers general device protection.

Frequently Asked Questions

What causes no module named pkg_resources?

It happens when setuptools is not installed in the Python environment that runs your code. pkg_resources is part of setuptools, so installing or reinstalling that package usually fixes the error immediately.

How do I fix pkg_resources on Python 3.12?

Run python -m pip install setuptools inside your environment. Python 3.12 virtual environments no longer include setuptools by default, so code that depended on it needs the package installed explicitly or needs updating.

Why does the error persist after I installed setuptools?

You probably installed it into a different Python than the one running your script. Use python -m pip with the interpreter you are using, activate your virtual environment, and check sys.executable to confirm.

Should I use pkg_resources in new code?

No. It is deprecated. Use importlib.metadata for version and entry-point lookups, and importlib.resources for data files. These are part of the standard library and do not need setuptools at runtime.

Is it safe to use sudo pip to fix this?

Avoid it. Installing into the system Python can conflict with operating system packages. Use a virtual environment, or on Debian and Ubuntu install python3-setuptools through apt if a system tool needs it.

Does pinning setuptools help?

Sometimes. If a newer setuptools release removes behaviour a library depends on, pinning an older version can work as a temporary fix. Update or replace the dependent library as soon as you can.

Conclusion

The pkg_resources error almost always means setuptools is missing from the active environment. Install it with python -m pip, confirm you are using the right interpreter, and rebuild broken virtual environments when needed. For your own projects, move to importlib.metadata and importlib.resources so the problem does not return.

Scroll to Top