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:
- Upgrade pip, setuptools and wheel in your environment.
- Install the latest version of the package, since newer releases often remove the old dependency.
- Install a prebuilt wheel if one exists for your Python version.
- Use
pip install --no-build-isolation package-nameafter installing setuptools yourself, if you understand the build requirements. - 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
- Activate the correct environment.
- Run
python -m pip install --upgrade setuptools. - Confirm with
python -c "import pkg_resources; print('ok')". - If a package build fails, upgrade pip and wheel as well.
- 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.

Tasha Harshman is a versatile writer who explores a range of topics with a special focus on entertainment. She enjoys sharing clear, engaging insights about movies, celebrities, trends, and pop culture.

