Getting started

This page covers how to get a working development checkout of ansible-core, run the CLIs from the source tree, and execute the test suite. For end-user installation (via pip install ansible-core or distro packages), see the official installation guide.

Prerequisites

• A POSIX OS. The CLIs (including ansible-test) do not run on native Windows — use WSL.
• Python 3.12 or newer for the controller. The minimum is enforced by _PY_MIN = (3, 12) in lib/ansible/cli/__init__.py.
• Git, plus make if you want to use the legacy build helpers.
• For most testing flows: Docker or Podman. ansible-test uses container images for hermetic test environments.

The runtime dependencies are listed in requirements.txt:

Dependency	Why
jinja2 >= 3.1.0	Templating engine — needs native macro support
PyYAML >= 5.1	YAML parsing
cryptography	Vault AES, password hashing helpers
packaging	Version comparisons and PEP 440 specifiers
resolvelib >= 0.8.0, < 2.0.0	Used by ansible-galaxy collection install to resolve dependencies

Editable install

git clone https://github.com/ansible/ansible.git
cd ansible
pip install -e .

This installs ansible-core in editable mode, so the ansible, ansible-playbook, etc. console scripts on your $PATH will run code from your checkout.

Running CLIs from the source tree without installing

bin/ contains symlinks that resolve to the real CLI modules. To run them in place, use the hacking/env-setup script (or hacking/env-setup.fish for fish):

source hacking/env-setup
ansible --version
ansible-playbook -i inventory site.yml

env-setup prepends bin/ to $PATH, sets PYTHONPATH to include lib/, and exports ANSIBLE_HOME, ANSIBLE_LIBRARY, etc. so plugins are picked up from the checkout.

Running tests

ansible-core's testing tool is ansible-test, packaged separately from the main library at test/lib/ansible_test/. The bin/ansible-test symlink points to its CLI stub.

Sanity tests (lint and static analysis)

# Run all sanity tests against the whole tree
ansible-test sanity -v --docker default

# Run a specific sanity test (e.g., pep8, pylint, mypy, validate-modules)
ansible-test sanity -v --docker default --test pep8 --test pylint

# Scope to specific files
ansible-test sanity -v --docker default lib/ansible/modules/command.py

Sanity tests use the default Docker image, defined in test/lib/ansible_test/_data/completion/docker.txt. They do not require any target machines.

Unit tests

Unit tests live under test/units/ and mirror the lib/ansible/ layout (test/units/cli/, test/units/executor/, etc.). They are pytest-based.

# Run all unit tests
ansible-test units -v --docker default

# Scope to a specific file
ansible-test units -v --docker default test/units/modules/test_command.py

# With coverage
ansible-test units -v --docker default --coverage

If Docker/Podman is unavailable, you can fall back to a virtualenv with --venv, but the documentation in AGENTS.md warns this is less reliable for unit and integration tests due to host environment differences.

Integration tests

Integration tests live under test/integration/targets/, with one subdirectory per feature or module (test/integration/targets/setup_remote_tmp_dir, test/integration/targets/template, etc.). They run real playbooks against a real (containerized) target.

# Run a single target on Ubuntu 24.04
ansible-test integration -v --docker ubuntu2404 setup_remote_tmp_dir

Integration tests must use a distro-specific container (ubuntu2204, ubuntu2404, fedora41, etc.). The default and base images are reserved for sanity/unit tests.

Local quick run without Docker

For a rapid smoke test without containers:

source hacking/env-setup
ansible -i 'localhost,' -c local -m ping localhost
ansible-playbook -i 'localhost,' -c local examples/site.yml

The trailing comma in 'localhost,' is required: -i accepts a comma-separated host list.

Where things land at runtime

Path	Purpose
~/.ansible/	User-level config, retry files, cached facts
~/.ansible/collections/	User-installed collections from ansible-galaxy
/etc/ansible/	System-wide config (ansible.cfg, optional inventory)
/usr/share/ansible/collections/	System-wide collections

Configuration precedence and full key listings come from lib/ansible/config/base.yml. See Reference → Configuration.

Next steps

• Read Architecture to understand how a playbook flows from CLI to remote target.
• Read How to contribute for the PR workflow expected in this repository.
• Read Patterns and conventions before opening a PR.