🚨 Ansible Error Guide: 'Failed to import the required Python library' (module dependency)

Overview

Many Ansible modules wrap a third-party Python library — community.docker needs docker, community.postgresql needs psycopg2, kubernetes.core needs kubernetes, community.mysql needs PyMySQL. The module runs in the remote (or local) Python interpreter and tries to import that library. If it is not installed in that exact interpreter, the module fails with Failed to import the required Python library.

You will see it on the task that uses the module:

fatal: [db-01]: FAILED! => {"changed": false, "msg": "Failed to import the required Python library (psycopg2) on db-01's Python /usr/bin/python3. 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 is unusually precise: it names the missing library, the host, and the exact interpreter path it tried. The library must be installed in that interpreter — installing it elsewhere (a venv, system Python 2, your control node) does nothing.

Symptoms

• A module that talks to a service (DB, Docker, K8s, cloud) fails with Failed to import the required Python library (<lib>).
• The message names a specific interpreter path like /usr/bin/python3.
• Installing the library “works” but the error persists (installed in the wrong Python).
• Local-action/delegate_to: localhost modules fail on the control node’s interpreter.

ansible db-01 -i inventory.ini -m community.postgresql.postgresql_info -b

db-01 | FAILED! => {
    "msg": "Failed to import the required Python library (psycopg2) on db-01's Python /usr/bin/python3."
}

Common Root Causes

1. The library is simply not installed in that interpreter

The dependency was never installed on the target host’s Python.

ansible db-01 -i inventory.ini -m raw -a '/usr/bin/python3 -c "import psycopg2; print(psycopg2.__version__)"'

ModuleNotFoundError: No module named 'psycopg2'

Install it into that exact Python:

ansible db-01 -i inventory.ini -m ansible.builtin.pip \
  -a 'name=psycopg2-binary executable=pip3' -b

2. Library installed in a different Python than Ansible uses

The library is present, but under a different interpreter (e.g. installed via pip into Python 3.9 while Ansible runs /usr/bin/python3 = 3.11).

ansible db-01 -i inventory.ini -m raw -a 'ls /usr/lib/python3*/dist-packages/ | grep -i psycopg; /usr/bin/python3 -c "import sys; print(sys.executable)"'

/usr/bin/python3

Match ansible_python_interpreter to the Python that has the library, or install into the one Ansible uses.

3. Installed in a virtualenv Ansible is not using

The dependency lives in a venv, but the module runs the system Python.

ansible-inventory -i inventory.ini --host db-01 | grep python_interpreter

"ansible_python_interpreter": "/usr/bin/python3"

If the lib is in /opt/app/venv, point the module at it:

- community.postgresql.postgresql_info:
  vars:
    ansible_python_interpreter: /opt/app/venv/bin/python

4. pip installed as the wrong user (no become)

The pip install ran as an unprivileged user into --user site-packages, but the module runs under become as root, which does not see it (or vice-versa).

ansible db-01 -i inventory.ini -m raw -a 'sudo /usr/bin/python3 -c "import psycopg2" 2>&1; /usr/bin/python3 -c "import psycopg2" 2>&1'

If only one of the two imports succeeds, the install user and the module’s effective user differ.

5. The dependency installed on the control node, not the target

For most modules the library is needed on the remote host. For delegate_to: localhost / local-action modules (many cloud modules), it is needed on the control node instead.

# remote module -> install on the target
# local/delegated module -> install on the controller
python3 -c "import boto3; print(boto3.__version__)"

ModuleNotFoundError: No module named 'boto3'

6. Missing system build dependency for a compiled library

psycopg2 (non-binary), cryptography, etc. need system dev headers; pip install fails silently or partially.

ansible db-01 -i inventory.ini -m raw -a 'apt-get install -y libpq-dev gcc python3-dev' -b

(Using the -binary wheel, e.g. psycopg2-binary, avoids needing a compiler.)

Diagnostic Workflow

Step 1: Read the library name and interpreter path from the error

Failed to import the required Python library (kubernetes) on app-01's Python /usr/bin/python3

Note both: the library to install, and the exact Python to install it into.

Step 2: Confirm the import in that exact interpreter

ansible app-01 -i inventory.ini -m raw -a '/usr/bin/python3 -c "import kubernetes; print(kubernetes.__version__)"'

A ModuleNotFoundError confirms it is missing in that interpreter specifically.

Step 3: Determine whether the module runs remotely or locally

grep -RnE 'delegate_to|local_action|connection: *local' roles/ playbooks/ 2>/dev/null

Local/delegated modules need the lib on the control node, not the target.

Step 4: Install into the matching interpreter (with the right user)

ansible app-01 -i inventory.ini -m ansible.builtin.pip \
  -a 'name=kubernetes executable=pip3' -b

Match become to how the module runs so the install lands in the right site-packages.

Step 5: Verify and re-run the module

ansible app-01 -i inventory.ini -m raw -a '/usr/bin/python3 -c "import kubernetes; print(\"ok\")"'
ansible app-01 -i inventory.ini -m kubernetes.core.k8s_info -a 'kind=Namespace' -b

ok

Example Root Cause Analysis

A playbook managing Postgres works on the old DB hosts but fails on a newly provisioned one:

fatal: [db-07]: FAILED! => {"msg": "Failed to import the required Python library (psycopg2) on db-07's Python /usr/bin/python3."}

A teammate “already installed it”, yet it still fails. Checking the import in the exact interpreter:

ansible db-07 -i inventory.ini -m raw -a '/usr/bin/python3 -c "import psycopg2" 2>&1; pip3 show psycopg2-binary 2>&1 | head -2'

ModuleNotFoundError: No module named 'psycopg2'

Then checking where the teammate actually installed it:

ansible db-07 -i inventory.ini -m raw -a 'ls /opt/pgtools/venv/lib/python3.11/site-packages/ | grep -i psycopg'

psycopg2_binary-2.9.9.dist-info

psycopg2-binary was installed into a project virtualenv at /opt/pgtools/venv, but Ansible runs the system /usr/bin/python3, which has no such package. The library is present — just in the wrong interpreter. The mismatch between the venv and Ansible’s interpreter is the root cause.

Fix: either install into the system Python the module uses, or point the task at the venv. Installing into the system Python keeps the role uniform with the other DB hosts:

ansible db-07 -i inventory.ini -m ansible.builtin.pip \
  -a 'name=psycopg2-binary executable=pip3' -b

ansible db-07 -i inventory.ini -m raw -a '/usr/bin/python3 -c "import psycopg2; print(\"ok\")"'

ok

The Postgres module now runs.

Prevention Best Practices

• Install module dependencies in the same play, into the same interpreter the module uses, with a pip task that runs before the module — so a fresh host is self-provisioning.
• Always confirm which interpreter Ansible uses (ansible_python_interpreter) and install the library there; the error message names the exact path for a reason.
• Prefer pre-built wheels (psycopg2-binary, etc.) to avoid needing system compilers and dev headers on managed hosts.
• For delegate_to: localhost / cloud modules, install the dependency on the control node and pin its interpreter, since the import happens there.
• Bake common module dependencies into your base images or a managed venv referenced consistently via ansible_python_interpreter, so installs are deterministic.
• When the same “missing library” error recurs across a fleet, the free incident assistant can group hosts by interpreter to spot the mismatch. See more in the Ansible guides.

Quick Command Reference

# Read library + interpreter from the error, then confirm the import there
ansible <host> -i inventory.ini -m raw -a '/usr/bin/python3 -c "import <lib>; print(\"ok\")"'

# What interpreter does Ansible use?
ansible-inventory -i inventory.ini --host <host> | grep python_interpreter

# Does the module run locally? (controller needs the lib instead)
grep -RnE 'delegate_to|local_action|connection: *local' roles/ playbooks/

# Install the dependency into the matching interpreter
ansible <host> -i inventory.ini -m ansible.builtin.pip -a 'name=<lib> executable=pip3' -b

# System build deps for compiled libs (or use the -binary wheel)
ansible <host> -i inventory.ini -m raw -a 'apt-get install -y libpq-dev gcc python3-dev' -b

Conclusion

Failed to import the required Python library means a module’s third-party dependency is not importable in the interpreter it runs in. The error helpfully names both the library and the exact interpreter. The usual root causes:

1. The library is not installed in that interpreter at all.
2. It is installed in a different Python than Ansible uses.
3. It lives in a virtualenv the module is not pointed at.
4. It was installed as the wrong user relative to become.
5. It is needed on the control node (for local/delegated modules), not the target.
6. A compiled library failed to build for lack of system dev headers.

Install the named library into the exact interpreter from the error message, matching the module’s become user and remote-vs-local context — that resolves nearly every case.