ansible.cfg: Complete Configuration Guide for Ansible (2026)
By Luca Berton · Published 2024-01-01 · Category: troubleshooting
Complete guide to ansible.cfg configuration file. Set defaults, SSH options, privilege escalation, inventory path, and performance tuning. All configuration options explained.
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.
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
Complete Configuration Reference
[defaults] Section
[privilege_escalation] Section
[ssh_connection] Section
[colors] Section
Environment Variable Overrides
Any setting can be overridden with environment variables:
Performance Tuning
Optimized ansible.cfg for Speed
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
Validate Configuration
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
Category: troubleshooting