Ansible pip module: No module named 'pkg_resources' (tested fix)

The Ansible pip module fails with "Failed to import the required Python library (setuptools)" and ModuleNotFoundError: No module named 'pkg_resources', even though setuptools is installed. Tested fixes: upgrade ansible-core, or install setuptools<81 on the target Python.

1. The error: the pip module says setuptools is missing

We ran the pip module against localhost with ansible-core 2.15.13. The target Python was a fresh Python 3.11 venv with setuptools 84.2.1, so setuptools was installed, but setuptools 82.0.0 removed pkg_resources:

$ ansible localhost -c local -m pip -a "name=six state=present" \
    -e ansible_python_interpreter=/path/to/venv/bin/python
[WARNING]: No inventory was parsed, only implicit localhost is available
An exception occurred during task execution. To see the full traceback, use -vvv. The error was: ModuleNotFoundError: No module named 'pkg_resources'
localhost | FAILED! => {
    "changed": false,
    "msg": "Failed to import the required Python library (setuptools) on myhost's Python /path/to/venv/bin/python. Please read the module documentation and install it in the appropriate location. If the required library is installed, but Ansible is using the wrong Python interpreter, please consult the documentation on ansible_python_interpreter"
}

The message blames setuptools, but the real error is in the "An exception occurred" line. In ansible-core 2.15.13, ansible/modules/pip.py does from pkg_resources import Requirement and treats any ImportError as "setuptools missing". Installing setuptools again does not help, because pip installs the newest version, which has no pkg_resources.

2. Fix A: upgrade ansible-core

With ansible-core 2.19.14 (the newest that pip installs on Python 3.11), the same command against the same kind of venv (setuptools 84.2.1) succeeded:

localhost | CHANGED => {
    "changed": true,
[... trimmed ...]

Its pip.py tries from packaging.requirements import Requirement first and only falls back to pkg_resources. We also checked the pip.py in the ansible-core 2.16.0 wheel, and it already has the packaging import, so 2.16 or newer should be enough. We only ran 2.15.13 and 2.19.14.

3. Fix B: cap setuptools on the target Python

If you can't upgrade ansible-core yet, install a setuptools that still includes pkg_resources into the interpreter the module runs with (the target's ansible_python_interpreter, not the control node):

$ /path/to/venv/bin/pip install "setuptools<81"     # got 80.10.2
$ ansible localhost -c local -m pip -a "name=six state=present" \
    -e ansible_python_interpreter=/path/to/venv/bin/python
localhost | CHANGED => {
    "changed": true,
[... trimmed ...]

In a playbook, don't do this with the pip module, since the module itself needs pkg_resources. Use a command task that runs <target python> -m pip install "setuptools<81".

Same root cause elsewhere: No module named 'pkg_resources' (general fix) · docker build · pipenv · Poetry.

Written with AI assistance. Measured on 2026-10-24 on Linux with ansible-core 2.15.13 and 2.19.14, CPython 3.11.17 target venvs with setuptools 84.2.1, running the pip module against localhost. Output pasted unedited except shortened paths and hostname. PlainTables is our extension; Ansible is free.