The error ModuleNotFoundError: No module named 'pkg_resources' means Python cannot find the pkg_resources module, which ships inside the setuptools package. The usual fix is to install setuptools in the active environment with pip install setuptools. If a package still fails, pin an older setuptools version, because recent releases removed pkg_resources.
This guide explains why the error appears now, the fixes in order of simplicity and how to stop depending on pkg_resources in your own code.
Why This Error Happens
- setuptools is missing: pkg_resources is part of setuptools, so a clean virtual environment without it fails. Developers report this often after moving to Python 3.12, where new environments do not include setuptools by default.
- setuptools removed the module: reports say pkg_resources was removed in newer setuptools releases, with some sources pointing to version 81 and others to 82. Packages that still import it then break.
- Wrong environment: you installed setuptools in one Python and run code in another.
- Isolated build: a package build runs in a temporary environment that lacks setuptools.
Fix 1: Install setuptools
python -m pip install setuptools
Use python -m pip so the install targets the same interpreter that runs your code. Then rerun the command that failed.
Fix 2: Pin an Older setuptools
If setuptools is installed but the error persists, a newer release may have dropped the module. Pin below the version where it disappeared:
python -m pip install "setuptools<81"
Because sources disagree on whether the removal happened in 81 or 82, using a version below 81 is the safer choice until the dependent package updates.
Fix 3: Check the Right Environment
- Activate your virtual environment.
- Run
python -c "import sys; print(sys.executable)"to confirm which Python is active. - Run
python -m pip show setuptoolsto confirm it is installed there.
Fix 4: System Packages on Linux
On Debian or Ubuntu with system Python, a guide suggests installing the distribution package, for example sudo apt install python3-pkg-resources. Package names vary by distro, so check yours.
Fix 5: Build Errors During pip install
If the error appears while installing a package, upgrade your tooling first and try a no-build-isolation install only if you understand the tradeoffs:
python -m pip install --upgrade pip setuptools wheel
Fix It in Your Own Code
If you maintain the code that imports pkg_resources, move to the standard library instead:
| Old pattern | Replacement |
|---|---|
pkg_resources.get_distribution("x").version |
importlib.metadata.version("x") |
pkg_resources.iter_entry_points |
importlib.metadata.entry_points() |
pkg_resources.resource_filename |
importlib.resources.files() |
Understanding tools like these is part of building digital skills; see our article on digital literacy in the age of AI or the guide to building sustainable digital businesses.
Frequently Asked Questions
What is pkg_resources?
It is a module in setuptools that helps Python work with installed packages and their resources.
Why did my project suddenly break?
A new setuptools release probably removed pkg_resources, or you created a new environment that lacks setuptools.
Does pip install setuptools always work?
It works if setuptools is missing. If a newer version removed the module, you need to pin an older one.
Should I use pkg_resources in new code?
No. Use importlib.metadata and importlib.resources instead.
Why does it fail only inside Docker or CI?
Fresh images may not include setuptools. Add it to your requirements or install step.
Which setuptools version should I pin?
Pin below 81 for safety, then update the dependent package that needs pkg_resources.
Conclusion
The pkg_resources error almost always comes down to setuptools: it is missing, in the wrong environment or too new. Install it with the right interpreter, pin an older version if needed and plan to replace pkg_resources with importlib in your own code. These steps fix most cases in a few minutes.

Doris Pollard, a mesmerizing wordsmith and experienced blogger, crafts narratives that carry readers into unexplored realms. Infused with insightful perspectives and vibrant storytelling, Doris’s mastery of language captivates both hearts and minds, making an enduring impression on the literary landscape.