Which ansible.cfg is actually in effect · Ansible

An operator raises forks from 5 to 50 in /etc/ansible/ansible.cfg to speed up a fleet-wide run. The run takes exactly as long as before. They raise it to 100. No change. They check the file three times; the value is there.

The setting was never read. A project ansible.cfg existed in the directory they ran from, and that file was the only configuration Ansible loaded.

Four locations, in order

Ansible looks in these places and stops at the first one that exists:

#	Location	Notes
1	`$ANSIBLE_CONFIG`	A file path, or a directory containing `ansible.cfg`
2	`./ansible.cfg`	The current working directory only
3	`~/.ansible.cfg`	The invoking user’s home directory
4	`/etc/ansible/ansible.cfg`	System-wide

One sentence carries most of the operational weight:

The first file found is used, and every other file is ignored completely. They do not merge.

Not “the higher-priority file wins where they conflict”. The others are not consulted at all. A setting that exists only in /etc/ansible/ansible.cfg has no effect from the moment a project ansible.cfg exists — even if the project file does not mention that setting.

Prove it. ~/.ansible.cfg sets both forks and timeout:

Read-only / Safehome config alone— With no project config present, both settings from the home file are in effect.

$ ansible-config dump --only-changed

CONFIG_FILE() = /home/ops/.ansible.cfg
DEFAULT_FORKS(/home/ops/.ansible.cfg) = 3
DEFAULT_TIMEOUT(/home/ops/.ansible.cfg) = 60

Illustrative output

Now add a project ansible.cfg that sets forks and inventory, and says nothing about timeout:

Read-only / Safeproject config present— The home file is not consulted, so its timeout setting disappears entirely rather than being overridden.

$ ansible-config dump --only-changed

CONFIG_FILE() = /srv/estate/ansible.cfg
DEFAULT_FORKS(/srv/estate/ansible.cfg) = 30
DEFAULT_HOST_LIST(/srv/estate/ansible.cfg) = ['/srv/estate/inventory']

Illustrative output

DEFAULT_TIMEOUT is gone. It has not been overridden by a different value — it has reverted to the built-in default of 10, because the file that set it was never opened. Both captures are from ansible-core 2.21.3; the paths have been shortened for the page.

The one command that answers the question

Before diagnosing anything about Ansible behaviour, establish which configuration is in force. ansible --version reports it on the second line:

Read-only / Safethe first troubleshooting step— Names the config file actually loaded, the Python running Ansible, and the ansible-core version. All three cause their own class of 'works on my controller' incident.

$ ansible --version

ansible [core 2.21.3]
config file = /srv/estate/ansible.cfg
configured module search path = ['/home/ops/.ansible/plugins/modules']
ansible python module location = /home/ops/.venvs/estate/lib/python3.12/site-packages/ansible
ansible collection location = /home/ops/.ansible/collections:/usr/share/ansible/collections
executable location = /home/ops/.venvs/estate/bin/ansible
python version = 3.12.7
jinja version = 3.1.4
pyyaml version = 6.0.3 (with libyaml v0.2.5)

Illustrative output

When no file is found anywhere, the line is explicit, and this is a real state rather than an error:

ansible [core 2.21.3]
  config file = None

Every setting is then at its built-in default: forks 5, timeout 10, host_key_checking true, inventory /etc/ansible/hosts.

The working directory is part of your configuration

Location 2 is ./ansible.cfg, and . means the current working directory. There is no search upward through parent directories.

This is worth stating plainly because it contradicts the mental model most people bring from Git, .editorconfig, tox.ini and every other project-root file they have used:

/srv/estate/
    ansible.cfg          <- the project configuration
    site.yml
    inventory/
    playbooks/
        patching.yml

Run from /srv/estate, the project config is found. Run from /srv/estate/playbooks, it is not — Ansible finds nothing in the current directory and falls through to ~/.ansible.cfg, then to /etc/ansible/ansible.cfg, then to nothing.

Confirmed on 2.21.3: invoking from a subdirectory of a project that has an ansible.cfg at its root reported config file pointing at the home directory file instead.

cd changes your forks, your inventory and your host key checking

The same command, run by the same person, from two directories in the same repository, can load two different configurations.

If the project config sets host_key_checking and the home config does not, then running from a subdirectory silently re-enables a security control — or, in the worse direction, running from a subdirectory silently loses a setting the project relied on.

Two defences, and they are not alternatives:

Set ANSIBLE_CONFIG explicitly in any wrapper, CI job or cron entry. It is location 1, so it wins regardless of where the process happens to start.
Never rely on the default inventory. Pass -i explicitly for anything that changes hosts, so that losing the config file cannot silently change which machines you are talking to.

Under the hood

Relative paths inside a config file are resolved against the directory containing the config file, not against the current working directory.

Verified on 2.21.3: with inventory = ./inventory in /srv/estate/ansible.cfg, invoked from an unrelated directory with ANSIBLE_CONFIG pointing at that file, ansible-config dump reported the inventory as /srv/estate/inventory.

That is the behaviour you want, and it is what makes a committed project config portable: the same file works for every developer, in every checkout path, and in CI, without anybody templating an absolute path into it. It applies to inventory, roles_path, collections_path, vault_password_file and the other path settings.

The corollary is that a config file is not freely relocatable. Moving ansible.cfg up or down one directory silently repoints every relative path in it, and the failure appears as an empty inventory or a missing role rather than as a path error.

`ANSIBLE_CONFIG` accepts a directory

A small convenience with a real use. ANSIBLE_CONFIG may name either a file or a directory; given a directory, Ansible looks for ansible.cfg inside it. Verified on 2.21.3.

ANSIBLE_CONFIG=/srv/estate ansible --version

That resolves to /srv/estate/ansible.cfg. It makes wrapper scripts and CI definitions a little less brittle — they point at the project root, which is a stable fact, rather than at a filename, which is a convention.

What happens if you want per-environment configuration?

You cannot have it through the search order, because there is only ever one file. There are two workable approaches and one that looks workable and is not.

Environment variables, set explicitly by the wrapper. Every configuration setting has a corresponding ANSIBLE_* variable, and those take precedence over the file. A production wrapper that exports ANSIBLE_FORKS=10 and ANSIBLE_TIMEOUT=30 before invoking is explicit, appears in the process environment, and is visible in ansible-config dump --only-changed as coming from the environment.

Separate config files selected by ANSIBLE_CONFIG. One file per environment, chosen by the wrapper. More duplication, but each file is complete and reviewable on its own — which matters, because the file that is loaded must contain everything.

What does not work: a base ansible.cfg plus a per-environment overlay expecting the two to combine. They will not. The overlay is the only file read, and every setting absent from it reverts to its built-in default rather than to the base file’s value.

Four locations, in order

The one command that answers the question

The working directory is part of your configuration

ANSIBLE_CONFIG accepts a directory

Knowledge check

`ANSIBLE_CONFIG` accepts a directory