The error ModuleNotFoundError: No module named ‘pkg_resources’ means Python cannot find the pkg_resources module, which ships inside the setuptools package. In nearly every case the fix is one of three things: install setuptools into the environment that is actually running your code, pin setuptools to an older release if a package still imports pkg_resources, or upgrade or replace the package that depends on it.
The error has become far more common lately. Newer Python virtual environments no longer include setuptools by default, and recent setuptools releases have started removing pkg_resources altogether. This guide explains why it happens, how to diagnose which case you are in, and the exact commands that fix it on Windows, macOS and Linux.
What pkg_resources Is and Why It Goes Missing
pkg_resources is an old helper module that lets Python code discover installed packages, read their metadata, and load entry points. For years it came bundled with setuptools, so any environment with setuptools also had pkg_resources. Many popular libraries and command-line tools imported it at startup without ever declaring setuptools as a dependency.
That shortcut is what breaks today. As one troubleshooting guide puts it, the error usually means the active Python environment does not have a working setuptools installation. Several things can cause that:
- A fresh virtual environment on Python 3.12 or newer. Starting with Python 3.12,
venvno longer installs setuptools automatically, so code that quietly relied on it fails on first import. - A setuptools release that dropped the module. Developers have reported the error appearing overnight after upgrading to recent setuptools versions; community posts point to versions 81 and 82 as the point where
pkg_resourceswas removed. - The wrong interpreter. You installed setuptools with one Python, but your script runs under another.
- Build isolation. A package being built from source runs in a temporary environment that lacks setuptools.
- A broken or partly uninstalled setuptools. This often follows a failed upgrade or manual cleanup.
Step 1: Confirm Which Python Is Running
Most “I already installed it” cases come from a mismatched interpreter. Before changing anything, check which Python and pip you are actually using:
python --version
python -c "import sys; print(sys.executable)"
python -m pip --version
python -m pip show setuptools
If pip show setuptools reports that the package is not found, setuptools is missing from that environment. If pip points to a different folder than sys.executable, you are mixing interpreters. Always use python -m pip rather than a bare pip command so the package lands in the interpreter you intend.
Step 2: The Quick Fix, Install or Reinstall Setuptools
In a plain environment, the quickest repair is:
python -m pip install --upgrade pip
python -m pip install setuptools
Then retry your command. If that works, you are done. If you see the error return, or the install succeeds but the import still fails, the installed setuptools may be too new to contain pkg_resources. Move to the next step.
Step 3: Pin Setuptools to an Older Version
When a library still does import pkg_resources and the maintainers have not updated it, installing the latest setuptools will not help, because the module no longer exists there. The practical workaround is to pin setuptools below the version where the module was removed:
python -m pip install "setuptools<81"
Reports differ on the exact release that removed the module, with some saying 81 and others 82, so using a bound of below 81 is the safer choice. Treat this as a bridge rather than a permanent solution. Pin it in your requirements.txt, constraints.txt or pyproject.toml so teammates and CI servers get the same behaviour:
setuptools<81
Step 4: Fix the Underlying Cause
Pinning keeps things running, but the lasting fix is removing the dependency on pkg_resources. Your options depend on whether the import lives in your own code or in a third-party package.
If the import is in your own code
Replace pkg_resources with the standard-library importlib.metadata, available since Python 3.8. It handles the two most common jobs, reading a version and loading entry points:
| Old pkg_resources call | Modern replacement |
|---|---|
pkg_resources.get_distribution("pkg").version |
importlib.metadata.version("pkg") |
pkg_resources.iter_entry_points("group") |
importlib.metadata.entry_points(group="group") |
pkg_resources.resource_filename(...) |
importlib.resources.files(...) |
pkg_resources.parse_version(...) |
packaging.version.Version(...) |
If the import is in a third-party package
Check whether a newer release of that package has already removed the import. Upgrade it, then run your program again:
python -m pip install --upgrade package-name
If no fixed release exists, open an issue with the maintainers, keep the setuptools pin in place, or look for an alternative library that is actively maintained.
Fixes for Specific Situations
| Situation | What to do |
|---|---|
| New virtual environment on Python 3.12+ | Run python -m pip install setuptools inside the activated environment. |
| Error appears while installing a package | Install setuptools first, then use pip install --no-build-isolation package if the build still cannot find it. |
| Debian or Ubuntu system Python | Install the system package with sudo apt install python3-pkg-resources or python3-setuptools. |
| Poetry or pipenv project | Add setuptools to the project dependencies and re-lock. |
| Docker image | Add the pinned setuptools install to the Dockerfile before installing other requirements. |
| PyInstaller or frozen app | Rebuild with a compatible setuptools version and check hidden imports. |
How to Prevent the Error Next Time
- Declare your dependencies. If any code you control needs setuptools at runtime, list it explicitly rather than assuming it is present.
- Use lock files and constraints. A locked set of versions means a new setuptools release cannot break a working build overnight.
- Create environments deliberately. After
python -m venv .venv, install what your project needs instead of relying on defaults. - Test against new releases. Run a scheduled CI job that installs the newest versions so you find breakage before your users do.
- Migrate away from pkg_resources. Treat each remaining import as technical debt to retire.
Good environment hygiene also helps across other tools. Teams that standardise their workflows tend to waste less time on avoidable breakage, a theme explored in our piece on how technology is making communication more accessible and our look at why decision intelligence is replacing plain business intelligence.
How to Check That the Fix Worked
After changing anything, verify the result instead of assuming it. Run a short test in the same environment that failed:
python -c "import pkg_resources; print(pkg_resources.__file__)"
python -m pip list | grep -i setuptools
If the first command prints a file path inside your environment’s site-packages folder, the module is available again. If it still fails, the installed setuptools is probably too new, so apply the pin from Step 3. On Windows, replace grep -i setuptools with findstr /i setuptools.
Finally, rerun the original command that triggered the error, such as the application, test suite or pip install that failed. Record the working versions in your requirements file straight away. A fix that lives only in your terminal history tends to be forgotten, and the same error returns the next time someone builds the project from scratch. If you work in a team, mention the change in your pull request so reviewers understand why the pin exists and when it can be removed.
Common Mistakes to Avoid
- Using sudo pip on a system Python. This can damage packages your operating system depends on. Use a virtual environment instead.
- Installing “pkg_resources” with pip. There is no separate package of that name to fix this. The module belongs to setuptools.
- Upgrading everything at once. Change one thing at a time so you know which step solved the problem.
- Ignoring the traceback. The last import line in the error tells you which package needs
pkg_resources. That is the one to upgrade or replace.
Frequently Asked Questions
Why does pip say setuptools is installed but the error remains?
Either pip belongs to a different Python than the one running your script, or the installed setuptools is new enough that it no longer contains pkg_resources. Compare sys.executable with the output of python -m pip --version, then pin setuptools to an older release.
Can I install pkg_resources directly with pip?
No. It is not a standalone package on PyPI that solves this error. It is a module inside setuptools, so you install or pin setuptools instead.
Is it safe to pin setuptools to an older version?
For most projects, yes, as a temporary measure. Older releases still work, but they stop receiving new features and eventually fixes. Plan to remove the dependency on pkg_resources so you can move to current releases.
Why did my code work yesterday and fail today?
A new setuptools release was probably installed automatically, for example in a fresh CI build or Docker image with unpinned dependencies. Pinning versions or using a lock file prevents this kind of surprise.
Does this affect Windows, macOS and Linux differently?
The cause is the same everywhere. The only real difference is that Debian and Ubuntu offer system packages such as python3-pkg-resources, while on Windows and macOS you generally fix it with pip inside a virtual environment.
What is the best long-term replacement?
Use importlib.metadata and importlib.resources from the standard library, plus the packaging library for version parsing. They are maintained with Python itself and do not depend on setuptools being installed.
Conclusion
The pkg_resources error looks alarming, but it comes down to setuptools being absent, mismatched or too new. Confirm your interpreter, install setuptools, pin it below the removal point if a dependency still needs the module, and then work toward importlib.metadata so the problem does not return.

Sarah Wilson is a versatile writer who covers a wide range of topics, with a strong specialty in entertainment. She delivers engaging, insightful content focused on movies, celebrities, trends, and pop culture.