Ansible-core overview

Ansible-core is the open-source IT automation engine that powers configuration management, application deployment, ad-hoc task execution, network automation, and multi-node orchestration. This repository contains the controller code, the small set of "core" modules that ship with the engine, the plugin framework, the ansible-test tool, and the packaging for the ansible-core PyPI distribution. Everything else in the broader Ansible ecosystem lives in collections published to Galaxy.

The project is a Python package (ansible-core on PyPI) that exposes a family of CLIs, the most prominent of which is ansible-playbook. Targets are reached without an agent, typically over SSH, by shipping a self-contained Python wrapper called AnsiBallZ to the remote host. The codebase is GPLv3-licensed (with lib/ansible/module_utils/ defaulting to BSD-2-Clause) and supports Python 3.12+ on the controller; modules support a wider Python range.

What you get from this repository

• Nine end-user CLIs built around a shared CLI base class (lib/ansible/cli/__init__.py): ansible, ansible-playbook, ansible-galaxy, ansible-config, ansible-console, ansible-doc, ansible-inventory, ansible-pull, ansible-vault.
• A tenth, separately-packaged CLI, ansible-test, that lives under test/lib/ansible_test/ and provides sanity, unit, and integration testing for both ansible-core and any collection.
• A task execution engine (lib/ansible/executor/) that turns parsed playbooks into work for a pool of forked worker processes, scheduled by a pluggable strategy (linear, free, host_pinned, debug).
• A plugin framework (lib/ansible/plugins/) covering 17 plugin types: action, become, cache, callback, cliconf, connection, doc_fragments, filter, httpapi, inventory, lookup, netconf, shell, strategy, terminal, test, vars.
• Core modules (lib/ansible/modules/) shipped with ansible-core: ~73 essential modules such as command, copy, file, apt, dnf, service, systemd, template, user, git, setup, package, pip.
• Galaxy and collection tooling (lib/ansible/galaxy/, lib/ansible/utils/collection_loader/) for fetching, installing, and importing the modular content collections that make up Ansible-the-distribution.
• Vault (lib/ansible/parsing/vault/__init__.py) for AES-encrypting variable files at rest.

What it is not

ansible-core no longer ships the universe of modules. Hundreds of formerly-bundled modules now live in collections (for example, community.general, ansible.posix, cloud.aws). The lib/ansible/config/ansible_builtin_runtime.yml file maps the historical short names (ec2, mysql_user, etc.) to their new fully-qualified collection names. New plugins are typically not accepted into ansible-core; they belong in collections.

Repository at a glance

Top-level path	Contents
bin/	Symlinks that resolve to the real CLI entry points in lib/ansible/cli/ (and ansible-test in test/lib/)
lib/ansible/	The Python package: CLI dispatch, executor, plugins, modules, parsing, inventory, vault, galaxy
lib/ansible/_internal/	Private machinery used across the controller (templating, RPC, datatag, worker, JSON profiles)
lib/ansible/module_utils/	Shared code that gets shipped to remote targets along with modules
lib/ansible/plugins/	All plugin types, plus the loader.py that resolves them
test/units/	pytest-based unit tests, mirroring the lib/ layout
test/integration/targets/	Per-feature integration test targets
test/lib/ansible_test/	The ansible-test tool — sanity tests, container drivers, dependency manifests
hacking/	Contributor scripts: dev environment setup, Azure Pipelines log fetcher, release helpers
changelogs/fragments/	Per-PR changelog fragments, merged at release time
.azure-pipelines/	The Azure DevOps pipeline that runs CI for every PR
packaging/	Source-tarball packaging configuration

Quick navigation

• New to the codebase? Start with the Architecture page for the dispatch path from bin/ansible-playbook down to a remote host.
• Setting up a dev environment? See Getting started.
• Looking for vocabulary? The Glossary collects the project-specific terms (handler, fact, AnsiBallZ, FQCN, vault id, etc.).
• Want to contribute? See How to contribute and the Patterns and conventions page.
• The lens pages — Apps, Systems, Plugins, Primitives, Features — drill into the codebase from different angles.