Configuration

ansible-core has dozens of config options that change behavior — fork count, default callback, SSH retries, timeouts, default inventory, plugin path, color output. The configuration system reads them from a layered set of sources with a defined precedence and exposes them as ansible.constants.C.<NAME> to the rest of the codebase.

Precedence (highest to lowest)

1. CLI flags — --forks 10, --inventory, etc. Resolved by each CLI's init_parser().
2. Environment variables — ANSIBLE_FORKS=10, ANSIBLE_INVENTORY, etc.
3. ansible.cfg — INI-format config file. Searched in order:
   1. ANSIBLE_CONFIG=<path> env var if set.
   2. ./ansible.cfg in the current directory (with a safety check: cwd must be world-writable-blocked).
   3. ~/.ansible.cfg.
   4. /etc/ansible/ansible.cfg.
4. Defaults — set in lib/ansible/config/base.yml.

The exact resolution lives in lib/ansible/config/manager.py:ConfigManager.

Files

File	Role
lib/ansible/config/base.yml	The single source of truth for every option: name, type, default, env var, ini key, description, version
lib/ansible/config/manager.py	ConfigManager — reads sources, resolves precedence, returns typed values
lib/ansible/constants.py	Public constants exposed as ansible.constants.C.<NAME>
lib/ansible/config/ansible_builtin_runtime.yml	Plugin/module redirect map — separate concern but in the same dir
lib/ansible/config/__init__.py	Constants enumerating valid config kinds

Option declaration

Every option is declared in base.yml:

DEFAULT_FORKS:
  default: 5
  description: Maximum number of forks Ansible will use to execute tasks on target hosts.
  env: [{ name: ANSIBLE_FORKS }]
  ini:
    - { key: forks, section: defaults }
  type: integer
  yaml: { key: defaults.forks }
  version_added: '0.0.1'

Fields:

• default — the fallback value.
• description — human-readable; surfaced in ansible-config list and ansible-doc.
• env — list of environment variable names that set this option (in order).
• ini — INI sections/keys that set this option.
• yaml — YAML key path for tools that prefer YAML config (less common).
• type — string, integer, boolean, list, pathspec, path, pathlist, etc.
• version_added — when the option was introduced.

type: pathspec and pathlist get special handling: paths are expanded against ~, env vars, and made absolute.

ConfigManager

The ConfigManager (lib/ansible/config/manager.py) is loaded once at startup. Its main entry points:

• get_config_value(name) — return the typed effective value.
• get_config_value_and_origin(name) — same, plus a string identifying which source set it (default, env: ANSIBLE_FORKS, ini: defaults.forks).
• get_configuration_definitions(plugin_type=None, name=None) — return the schema for one or all options. Used by ansible-config list.

Plugins extend the option set: each plugin's DOCUMENTATION block can declare its own config options under an options: key, with the same env/ini/vars/description/version_added shape. The plugin loader feeds those options into the same ConfigManager. That's why a plugin can declare vars: [{name: ansible_user}] and have the user override it with a set_fact at playbook time.

Examples of options grouped by where they're consumed

• Default behavior (DEFAULT_*): forks, host pattern style, callbacks loaded, modules to skip during fact gathering.
• SSH (ANSIBLE_SSH_*, DEFAULT_SSH_TRANSFER_METHOD): control persist, sftp vs. scp, connect timeout.
• Inventory (INVENTORY_*): enabled inventory plugins, ignored extensions, ignored patterns.
• Becoming (DEFAULT_BECOME*): become method, user, password file.
• Galaxy (GALAXY_*): API server URL, signature verification, ignore deprecated.
• Collections (COLLECTIONS_*): paths, on-missing-action.
• Vault (DEFAULT_VAULT_*): identity list, password file, encryption format options.
• Display (DEFAULT_*COLOR*, ANSIBLE_FORCE_COLOR, NOCOLOR): output styling.

Inspecting effective config

Use ansible-config:

ansible-config list                   # every option, with descriptions and defaults
ansible-config dump                   # only options with non-default values
ansible-config dump --only-changed    # explicit
ansible-config view                   # display the active ansible.cfg with vault decrypt
ansible-config init --disabled        # write a starter ansible.cfg with all options commented out
ansible-config validate file.cfg      # check for typos and unknown keys

The CLI dispatches into lib/ansible/cli/config.py (28k lines) which formats the ConfigManager's output.

How plugins read config

A plugin doesn't access ansible.constants.C directly; it uses the auto-wired option machinery from lib/ansible/plugins/__init__.py:AnsiblePlugin:

class MyConnection(ConnectionBase):
    def some_method(self):
        host = self.get_option('host')
        port = self.get_option('port')

The plugin's DOCUMENTATION declares the options; the plugin loader populates them via set_options() (called with the play's vars, the inventory's vars, and any direct keyword passes). At call time get_option(name) walks the precedence list (vars > env > ini > default) and returns the value.

INI quirks

The INI parser (configparser) is used directly. A few things to know:

• Sections are case-sensitive; the [defaults] section is the catch-all.
• Booleans accept yes/no/true/false/1/0 (per lib/ansible/module_utils/parsing/convert_bool.py).
• Paths under [defaults] like inventory = /etc/hosts are interpreted relative to the cwd, but host_key_checking = false doesn't have an equivalent.
• Comments are # or ;. INI inline comments after a value require a leading space.

Versioning and deprecation

Every option has a version_added. Many also have a deprecated: block listing version, alternatives, and why. ansible-config list includes deprecation notes; running with a deprecated option emits a display.deprecated warning that the user sees once per process.

Integration points

• Imported by: nearly every controller-side module via from ansible import constants as C or from ansible.config.manager import ConfigManager.
• Read by: lib/ansible/cli/__init__.py:CLI.__init__ (very early), then propagated to all loaded plugins.
• Cached in: lib/ansible/constants.py:_CONFIG_VALUE (a process-lifetime cache; reloading config requires restart).

Entry points for modification

• Adding an option — declare it in lib/ansible/config/base.yml, then access it via C.<NAME> or ConfigManager.get_config_value. Add a sanity-test entry if the option name doesn't already match the runtime-metadata expectations.
• Renaming an option — add a deprecated: block with the old name, then add the new entry. Both will be honored for the deprecation cycle.
• Plugin-specific options — declare them under options: in the plugin's DOCUMENTATION. The auto-wiring picks them up.

Cross-links

• Apps → ansible-config — the CLI surface.
• Plugin loader — where vars/env/ini precedence is implemented.
• Reference → Configuration — the canonical option list.