AnsibleByExample

Fix ModuleNotFoundError: No module named 'ansible'

Beginneransibletroubleshootingpythoninstallation
2024-01-016By Luca Berton

Lesson 1 of 20 in Production Playbooks

Production Playbooks and Troubleshooting — full curriculum
  1. 1. Advanced Playbook Structure & Execution Strategies
  2. 2. Deep Dive: Variable Precedence & Best Practices
  3. 3. Jinja2 Templating Beyond Basics
  4. 4. Advanced Conditionals
  5. 5. Loops Masterclass
  6. 6. Blocks, Rescue, Always (Error Handling)
  7. 7. Handlers Advanced
  8. 8. Change Control: changed_when, failed_when
  9. 9. Tags and Selective Runs
  10. 10. Performance Tuning
  11. 11. Delegation Patterns
  12. 12. Local Actions and Remote Actions
  13. 13. Dynamic Inventory & Runtime Host Management
  14. 14. Includes & Imports (Structuring Large Codebases)
  15. 15. Role Design Patterns
  16. 16. Ansible Galaxy & Collections in Real Projects
  17. 17. Working with APIs (uri + JSON workflows)
  18. 18. Testing and Linting (Quality Gates)
  19. 19. Advanced Debugging Playbook Failures
  20. 20. Capstone: Multi-Stage Deployment
View path overview →

Introduction

The ModuleNotFoundError: No module named 'ansible' error occurs when Python cannot find the Ansible package in its module search path. This typically happens when Ansible is installed in a different Python environment than the one your script uses, or when using ansible-core (which doesn't provide the ansible top-level package the same way). This article covers every common cause and its fix.

The Error

Example Script

#!/usr/bin/env python3
from ansible.release import __version__
print(__version__)

Error Output

$ python3 example.py
Traceback (most recent call last):
  File "example.py", line 2, in <module>
    from ansible.release import __version__
ModuleNotFoundError: No module named 'ansible'

Cause 1: Ansible Not Installed for This Python

The most common cause — Ansible is installed with a different Python version or not installed at all.

Diagnose

# Which Python is running your script?
which python3
python3 --version

# Is ansible installed for THIS Python?
python3 -m pip show ansible
python3 -m pip show ansible-core

# Where is ansible-playbook?
which ansible-playbook

# What Python does ansible use?
ansible --version | grep python

Fix

# Install ansible for the Python your script uses
python3 -m pip install ansible

# Or install just ansible-core (smaller)
python3 -m pip install ansible-core

Cause 2: Multiple Python Versions

Many systems have Python 3.9, 3.10, 3.11, and 3.12 installed simultaneously. Ansible might be under one version while your script runs another.

Diagnose

# List all Python versions
ls /usr/bin/python3*
ls /usr/local/bin/python3*

# Check each for ansible
python3.11 -m pip show ansible-core
python3.12 -m pip show ansible-core

# Check what /usr/bin/python3 points to
python3 -c "import sys; print(sys.executable)"

Fix

# Option 1: Install ansible for the specific Python
python3.12 -m pip install ansible

# Option 2: Use the same Python as ansible
ANSIBLE_PYTHON=$(ansible --version | grep 'python version' | grep -o '/[^ ]*')
$ANSIBLE_PYTHON example.py

# Option 3: Use a shebang that matches
#!/usr/bin/env python3.11

Cause 3: Virtual Environment Not Activated

Ansible is in a virtualenv, but your script runs outside it (or vice versa).

Diagnose

# Are you in a virtualenv?
echo $VIRTUAL_ENV

# Check if ansible is in the venv
pip show ansible-core

# Check Python path
python3 -c "import sys; print('\n'.join(sys.path))"

Fix

# Activate the virtualenv first
source /path/to/venv/bin/activate
python3 example.py

# Or use the venv's Python directly
/path/to/venv/bin/python3 example.py

Create a Dedicated Ansible Virtual Environment

# Create venv
python3 -m venv ~/ansible-venv

# Activate
source ~/ansible-venv/bin/activate

# Install ansible
pip install ansible

# Verify
python3 -c "from ansible.release import __version__; print(__version__)"

# Add to shell profile for persistence
echo 'source ~/ansible-venv/bin/activate' >> ~/.bashrc

Cause 4: pipx Installation

If you installed Ansible with pipx, it's isolated and not available to other Python scripts.

Diagnose

# Check if ansible was installed via pipx
pipx list | grep ansible

Fix

# Option 1: Install ansible with regular pip instead
pip install ansible

# Option 2: Run your script inside the pipx environment
pipx run --spec ansible python3 example.py

# Option 3: Inject your script's dependencies into ansible's pipx env
pipx inject ansible your-package

Cause 5: ansible-core vs ansible Package

ansible-core provides the core runtime (ansible.builtin), while the ansible package includes ansible-core plus community collections. Both provide the ansible Python module, but ansible-compat does NOT.

Diagnose

# Check what's installed
pip show ansible
pip show ansible-core
pip show ansible-compat

# ansible-compat requires ansible-core but doesn't install the 'ansible' module itself

Fix

# Install ansible-core (minimum) or ansible (full)
pip install ansible-core    # just the runtime
pip install ansible          # runtime + collections

Cause 6: System Package Manager Conflicts

On some Linux distributions, the system ansible package installs to a different location than pip expects.

Diagnose

# Check if ansible is a system package
dpkg -l ansible 2>/dev/null       # Debian/Ubuntu
rpm -qa | grep ansible 2>/dev/null # RHEL/Fedora

# Check pip vs system locations
pip show ansible-core | grep Location
python3 -c "import ansible; print(ansible.__file__)"

Fix

# Option 1: Use the system Python
/usr/bin/python3 example.py

# Option 2: Remove system package, install via pip
sudo apt remove ansible   # or dnf remove ansible
pip install ansible

# Option 3: Use --user flag
pip install --user ansible

Cause 7: Wrong User (sudo vs Regular)

If Ansible was installed with sudo pip, it may not be available to your regular user, or vice versa.

Diagnose

# Check as regular user
pip show ansible-core

# Check as root
sudo pip show ansible-core

Fix

# Install for your user
pip install --user ansible

# Or use a virtualenv (preferred)
python3 -m venv ~/ansible-venv
source ~/ansible-venv/bin/activate
pip install ansible

Complete Diagnostic Script

#!/bin/bash
echo "=== Python ==="
which python3
python3 --version
python3 -c "import sys; print('Path:', sys.executable)"

echo ""
echo "=== Ansible CLI ==="
which ansible 2>/dev/null || echo "ansible not in PATH"
ansible --version 2>/dev/null | head -3 || echo "ansible not available"

echo ""
echo "=== pip packages ==="
python3 -m pip show ansible 2>/dev/null || echo "ansible not installed"
python3 -m pip show ansible-core 2>/dev/null || echo "ansible-core not installed"

echo ""
echo "=== Virtual Environment ==="
echo "VIRTUAL_ENV: ${VIRTUAL_ENV:-not set}"

echo ""
echo "=== Python Path ==="
python3 -c "import sys; print('\n'.join(sys.path))"

echo ""
echo "=== Import Test ==="
python3 -c "from ansible.release import __version__; print('ansible', __version__)" 2>&1

Quick Fix Summary

SituationCommand
Ansible not installedpip install ansible
Wrong Python versionpython3.X -m pip install ansible
Virtualenv not activesource venv/bin/activate
pipx isolationpip install ansible (use regular pip)
Only ansible-compatpip install ansible-core
System vs pip conflictUse virtualenv
sudo vs user mismatchpip install --user ansible

Best Practices

  1. Always use virtual environments — isolate Ansible from system Python
  2. Use python3 -m pip instead of bare pip — ensures correct Python
  3. Match Python versions — use the same Python for scripts and Ansible
  4. Prefer ansible-core if you only need the runtime (smaller install)
  5. Avoid sudo pip install — use --user or virtualenv instead
  6. Pin versions in requirements.txt for reproducibility

Conclusion

The ModuleNotFoundError: No module named 'ansible' error is always a Python environment issue — the Python running your script can't find the Ansible package. The fix is to ensure Ansible is installed in the same Python environment your script uses. Virtual environments are the most reliable solution: create one, install Ansible in it, and run all your scripts from within it.

All Tutorials