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.metadatato read installed package versions and entry points. - Use
importlib.resourcesto access data files bundled inside packages. - Use the
packaginglibrary 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.

Sarah Wilson, an accomplished writer and seasoned blogger, weaves compelling narratives that transport readers to new and uncharted worlds. With a talent for vivid storytelling and thoughtful insight, her work leaves a lasting mark, enchanting both the imagination and intellect.
