Ansible Configuration File

Ansible reads a plain text file named ansible.cfg to decide how it behaves. Think of it as the settings menu on a phone. Brightness, volume, and language live in one place, and every app follows those choices. The configuration file holds defaults such as the inventory location, the login user, the number of parallel connections, and the folder that stores roles.

Where Ansible Looks for the File

Ansible checks four locations in a fixed order and stops at the first match. Ansible never merges two files. The winning file supplies every setting, and anything it leaves out falls back to a built-in default.

  1. The path stored in the ANSIBLE_CONFIG environment variable
  2. The file ansible.cfg in the current working directory
  3. The file .ansible.cfg in the home directory
  4. The file /etc/ansible/ansible.cfg for the whole system

Diagram: The Lookup Order

  You run: ansible-playbook site.yml
                  │
                  ▼
  ┌───────────────────────────────┐
  │ 1. ANSIBLE_CONFIG variable?   │── yes ──▶ use it
  └───────────────┬───────────────┘
                  │ no
                  ▼
  ┌───────────────────────────────┐
  │ 2. ./ansible.cfg exists?      │── yes ──▶ use it
  └───────────────┬───────────────┘
                  │ no
                  ▼
  ┌───────────────────────────────┐
  │ 3. ~/.ansible.cfg exists?     │── yes ──▶ use it
  └───────────────┬───────────────┘
                  │ no
                  ▼
  ┌───────────────────────────────┐
  │ 4. /etc/ansible/ansible.cfg   │──────────▶ use it
  └───────────────────────────────┘

File Structure

The file uses the INI format. Square brackets mark a section, and each line below holds a key = value pair. Lines that start with a # or a ; are comments.

[defaults]
inventory          = ./inventory
remote_user        = deploy
forks              = 20
roles_path         = ./roles
host_key_checking  = False
retry_files_enabled = False

[privilege_escalation]
become             = True
become_method      = sudo
become_user        = root

[ssh_connection]
pipelining         = True
ssh_args           = -o ControlMaster=auto -o ControlPersist=60s

Settings Worth Knowing

SettingSectionWhat It Controls
inventorydefaultsPath to the host list
remote_userdefaultsAccount used for SSH login
forksdefaultsNumber of hosts handled in parallel
roles_pathdefaultsFolders that hold roles
host_key_checkingdefaultsPrompt for new SSH fingerprints
interpreter_pythondefaultsPython path on managed hosts
becomeprivilege_escalationRun tasks with admin rights
pipeliningssh_connectionFewer SSH round trips per task

Check Which File Is Active

Run ansible --version to see the path of the configuration file in use. Run ansible-config dump --only-changed to list every setting that differs from the default. Run ansible-config list to browse all available options with descriptions.

$ ansible --version
ansible [core 2.16.4]
  config file = /home/deploy/webproject/ansible.cfg
  configured module search path = ['/home/deploy/.ansible/plugins/modules']

Environment Variables Override the File

Every setting has a matching environment variable that starts with ANSIBLE_. The variable beats the file for a single command. This approach suits a quick test without editing anything.

ANSIBLE_FORKS=50 ansible-playbook site.yml

Project Level Configuration

Most teams store an ansible.cfg file at the root of each project and commit it to version control. Every teammate runs identical settings. The project folder looks like this:

webproject/
├── ansible.cfg
├── inventory
├── site.yml
└── roles/

Ansible ignores a configuration file stored in a world-writable directory. This protection stops another user on the same machine from planting a malicious file. Run chmod 755 on the folder to fix the warning.

Common Mistakes

  • Editing /etc/ansible/ansible.cfg while a project file already wins the lookup
  • Expecting two files to combine their settings
  • Disabling host key checking on production systems, which removes a safety check
  • Placing a setting in the wrong section, which makes Ansible ignore it silently

Try This

Create a folder named cfgtest and add an ansible.cfg file with forks = 3. Run ansible-config dump --only-changed inside the folder. Move one level up and run the same command. Compare both outputs to watch the lookup order change the active file.

Summary

The ansible.cfg file stores defaults for every Ansible command. Ansible picks one file from four possible locations and never merges them. The INI format groups settings into sections such as defaults, privilege_escalation, and ssh_connection. Environment variables override the file for a single run. A project level file under version control keeps behavior identical across a whole team.