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.
- The path stored in the
ANSIBLE_CONFIGenvironment variable - The file
ansible.cfgin the current working directory - The file
.ansible.cfgin the home directory - The file
/etc/ansible/ansible.cfgfor 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
| Setting | Section | What It Controls |
|---|---|---|
| inventory | defaults | Path to the host list |
| remote_user | defaults | Account used for SSH login |
| forks | defaults | Number of hosts handled in parallel |
| roles_path | defaults | Folders that hold roles |
| host_key_checking | defaults | Prompt for new SSH fingerprints |
| interpreter_python | defaults | Python path on managed hosts |
| become | privilege_escalation | Run tasks with admin rights |
| pipelining | ssh_connection | Fewer 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.cfgwhile 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.
