ModuleNotFoundError: No module named 'pkg_resources' (tested fix)

ModuleNotFoundError: No module named 'pkg_resources' now has a new cause: setuptools 82.0.0 removed pkg_resources, so installing setuptools no longer brings it back. We tested every setuptools release from 80.9 to 84.2.1.

1. Installing setuptools no longer fixes it

We ran this in a fresh python:3-alpine container (Python 3.14.7, no setuptools preinstalled):

python -c "import sys; print(sys.version.split()[0])"
python -c "import pkg_resources" 2>&1 | tail -1
pip install -q --disable-pip-version-check --root-user-action=ignore setuptools 2>&1 | tail -1
pip show setuptools 2>/dev/null | grep '^Version'
python -c "import pkg_resources; print('ok')" 2>&1 | tail -1

Output:

3.14.7
ModuleNotFoundError: No module named 'pkg_resources'
Version: 84.2.1
ModuleNotFoundError: No module named 'pkg_resources'

pkg_resources was never part of the standard library: it came with setuptools. The old advice, "pip install setuptools", now installs the latest setuptools (84.2.1 when we tested), which does not contain pkg_resources any more. So the error survives the usual fix.

2. pkg_resources was removed in setuptools 82

for v in 81.0.0 82.0.0; do
  pip install -q --disable-pip-version-check --root-user-action=ignore "setuptools==$v" >/dev/null 2>&1
  echo "--- setuptools $v"
  python -c "import pkg_resources; print('import ok')" 2>&1 | grep -v '^ \|^Traceback'
done

Output:

--- setuptools 81.0.0
<string>:1: UserWarning: pkg_resources is deprecated as an API. See https://setuptools.pypa.io/en/latest/pkg_resources.html. The pkg_resources package is slated for removal as early as 2025-11-30. Refrain from using this package or pin to Setuptools<81.
import ok
--- setuptools 82.0.0
ModuleNotFoundError: No module named 'pkg_resources'

81.0.0 still ships it with a deprecation warning (that warning says it is "slated for removal as early as 2025-11-30" and suggests pinning Setuptools<81); 82.0.0 is the first release without it. We also checked 80.9.0 (works) and 83.0.0 (fails).

3. Short-term fix: pin setuptools below 82

pip install -q --disable-pip-version-check --root-user-action=ignore "setuptools<82" >/dev/null 2>&1
pip show setuptools 2>/dev/null | grep '^Version'
python -W ignore -c "import pkg_resources; print('import ok')"

Output:

Version: 81.0.0
import ok

Use this to unblock an old tool or package you cannot change, and put the pin in your requirements file so a later upgrade does not undo it. It is a stopgap: older setuptools will not get new fixes.

4. Proper fix: switch to importlib.metadata and importlib.resources

from importlib.metadata import version, PackageNotFoundError, entry_points
from importlib.resources import files
print(version("pip"))                        # was pkg_resources.get_distribution("pip").version
try:
    version("not-installed-pkg")
except PackageNotFoundError as e:            # was pkg_resources.DistributionNotFound
    print("PackageNotFoundError:", e)
print(files("json").joinpath("__init__.py").is_file())   # was resource_filename / resource_string
print(len(entry_points(group="console_scripts")) > 0)  # was iter_entry_points("console_scripts")

Output:

26.2.1
PackageNotFoundError: No package metadata was found for not-installed-pkg
True
True

Both modules are in the standard library (Python 3.8+ for metadata, 3.9+ for files()), so the replacement needs no dependency. Output above is from Python 3.14.7; version() reads the installed distribution name, the same string you pass to pip.

5. Fails during pip install even though setuptools is installed

If the traceback appears under "Getting requirements to build wheel" while pip is installing a package, the package's own setup.py imports pkg_resources. pip builds it in an isolated environment with the newest setuptools, so pinning setuptools in your venv does not reach that build. Pass the pin to the build instead (pip 26.2+):

echo "setuptools<81" > build-constraints.txt
pip install --build-constraint build-constraints.txt <package>

We tested this on cx_Oracle 8.3.0 and an old openai CLIP commit. Both failed without it and installed with it. On pip 26.2.2, PIP_CONSTRAINT did not reach the build environment. The environment-variable form of the right option did: PIP_BUILD_CONSTRAINT=build-constraints.txt pip install cx_Oracle==8.3.0 installed it, and the same command without the variable failed. Use that in a Dockerfile (ENV PIP_BUILD_CONSTRAINT=...) or CI job when you cannot edit the pip command. --no-build-isolation (with setuptools<81 in the venv) also worked for cx_Oracle. Full outputs: cx_Oracle · openai CLIP.

Related: PyTorch 1.10 to 2.1 · Home Assistant 2023.8 and older · Odoo 16 · Stable Diffusion WebUI · Trac 1.6 · supervisord · deluge 2.2.0 · paster (PasteScript) · jenkins-jobs (JJB) · mim (OpenMMLab) · pyqt5-tools designer · pyqt6-tools designer · opsdroid · nameko · python -m eel · Open Interpreter · wfuzz · nnictl (NNI) · embedchain ec · import yolov5 · scrapyd · No module named 'distutils' · ModuleNotFoundError vs ImportError · librosa 0.10.1 and older hit this error (tested fix) · TensorBoard 2.20 and older (tested fix) · pip install cx_Oracle (tested fix) · selenium-wire (tested fix) · openai CLIP (tested fix) · uv (tested pyproject fix) · Poetry (tested fix) · pipenv (tested fix) · docker build (tested Dockerfile) · Ansible pip module (tested fix) · import fs / PyFilesystem2 (tested fix) · UserWarning: pkg_resources is deprecated as an API.

Written with AI assistance. Measured on 2026-10-22 in the official python:3-alpine image (Python 3.14.7): importing pkg_resources with no setuptools and with setuptools 80.9.0, 81.0.0, 82.0.0, 83.0.0 and 84.2.1, and the importlib.metadata / importlib.resources replacements. Every block was run verbatim and its output pasted unedited. PlainHeaders is our extension; Python and setuptools are free.