ansible.cfg: Complete Configuration Guide for Ansible (2026)

What Is ansible.cfg?

ansible.cfg is the configuration file that controls Ansible's behavior. It sets defaults for connections, privilege escalation, inventory paths, logging, and performance.

See also: Ansible Disable SSH Host Key Checking: Configuration Guide

Configuration File Precedence

Ansible checks for configuration in this order (first found wins): ANSIBLE_CONFIG environment variable ansible.cfg in the current directory ~/.ansible.cfg in your home directory /etc/ansible/ansible.cfg system-wide default

Best practice: Keep ansible.cfg in your project directory alongside playbooks.

Minimal ansible.cfg

[defaults]
inventory = inventory/hosts.yml
remote_user = ansible
host_key_checking = False
retry_files_enabled = False
[privilege_escalation]
become = True
become_method = sudo
become_user = root
become_ask_pass = False

See also: 10 Proven Methods to Optimize Ansible Playbook Performance

Complete Configuration Reference

[defaults] Section

[defaults]
# Inventory
inventory = inventory/hosts.yml
# or multiple sources:
# inventory = inventory/static.yml,inventory/dynamic.py
# Connection
remote_user = ansible
remote_port = 22
transport = ssh
timeout = 30
# Output
stdout_callback = yaml
# Options: default, yaml, json, debug, minimal, dense
display_skipped_hosts = False
display_ok_hosts = True
# Performance
forks = 20
# Default is 5 - increase for large inventories
pipelining = True
# Reduces SSH operations - requires requiretty disabled in sudoers
# Gathering
gathering = smart
# Options: smart (cache), implicit (always), explicit (never)
gather_subset = !hardware,!facter
# Skip slow fact gathering
fact_caching = jsonfile
fact_caching_connection = /tmp/ansible-facts
fact_caching_timeout = 3600
# Paths
roles_path = roles:~/.ansible/roles:/usr/share/ansible/roles
collections_path = collections:~/.ansible/collections
library = library
module_utils = module_utils
filter_plugins = filter_plugins
# Logging
log_path = /var/log/ansible.log
# Uncomment to enable logging
# Security
host_key_checking = False
# Disable for lab/dev; enable for production
vault_password_file = ~/.vault_pass
# Auto-provide vault password
# Retry
retry_files_enabled = False
# Disable .retry file creation
# Python
interpreter_python = auto_silent
# Options: auto, auto_silent, auto_legacy, /usr/bin/python3

[privilege_escalation] Section

[privilege_escalation]
become = True
become_method = sudo
become_user = root
become_ask_pass = False
# Set True to prompt for sudo password

[ssh_connection] Section

[ssh_connection]
ssh_args = -o ControlMaster=auto -o ControlPersist=60s -o StrictHostKeyChecking=no
# Persistent SSH connections for performance
control_path_dir = ~/.ansible/cp
control_path = %(directory)s/%%h-%%r-%%p
pipelining = True
# Significant performance improvement
scp_if_ssh = smart
# Use SCP as fallback if SFTP fails
transfer_method = smart
# Options: smart, sftp, scp, piped

[colors] Section

[colors]
highlight = white
verbose = blue
warn = bright purple
error = red
debug = dark gray
deprecate = purple
skip = cyan
unreachable = red
ok = green
changed = yellow

Environment Variable Overrides

Any setting can be overridden with environment variables:

# Override inventory
export ANSIBLE_INVENTORY=production/hosts.yml
# Override forks
export ANSIBLE_FORKS=50
# Override remote user
export ANSIBLE_REMOTE_USER=deploy
# Disable host key checking
export ANSIBLE_HOST_KEY_CHECKING=False
# Set vault password file
export ANSIBLE_VAULT_PASSWORD_FILE=~/.vault_pass

See also: ansible.cfg Configuration File: Complete Settings Guide (2026)

Performance Tuning

Optimized ansible.cfg for Speed

[defaults]
forks = 50
gathering = smart
fact_caching = jsonfile
fact_caching_connection = /tmp/ansible-facts
fact_caching_timeout = 86400
stdout_callback = yaml
display_skipped_hosts = False
any_errors_fatal = False
[ssh_connection]
pipelining = True
ssh_args = -o ControlMaster=auto -o ControlPersist=600s -o PreferredAuthentications=publickey

Key Performance Settings

| Setting | Default | Recommended | Impact | |---------|---------|-------------|--------| | forks | 5 | 20-50 | Parallel host execution | | pipelining | False | True | Reduces SSH operations by 2x | | gathering | implicit | smart | Caches facts, skips re-gathering | | fact_caching | memory | jsonfile | Persists facts across runs | | strategy | linear | free | Hosts don't wait for each other |

Project Structure Example

project/
├── ansible.cfg          # Project configuration
├── inventory/
│   ├── production.yml
│   └── staging.yml
├── group_vars/
│   ├── all.yml
│   └── webservers.yml
├── roles/
│   └── webserver/
├── playbooks/
│   ├── deploy.yml
│   └── patch.yml
└── collections/
    └── requirements.yml

Validate Configuration

# Show current config and source
ansible-config view
# List all settings with current values
ansible-config dump
# Show only changed settings
ansible-config dump --only-changed
# List all available settings
ansible-config list

FAQ

Where should I put ansible.cfg?

In your project root directory, next to your playbooks. This makes the configuration portable and version-controlled. Avoid using ~/.ansible.cfg for project-specific settings.

Is ansible.cfg required?

No. Ansible works with built-in defaults. However, a project-specific ansible.cfg improves consistency, performance, and developer experience across your team.

How do I check which ansible.cfg is being used?

Run ansible --version. The output shows config file = /path/to/ansible.cfg. You can also set ANSIBLE_CONFIG environment variable to force a specific file.

Can I use YAML format for ansible.cfg?

No. ansible.cfg uses INI format only. However, you can set all the same values using environment variables (ANSIBLE_*) or command-line flags.

Related Articles

• Ansible Inventory Guide • Ansible Vault Guide • Ansible Performance Tuning • Ansible SSH Password Authentication