Ansible CFG File Path: Configuration Location Precedence in Different Environments

Ansible resolves the ansible.cfg file path using a strict four-tier precedence chain beginning with the ANSIBLE_CONFIG environment variable, then checking the current working directory, user home directory, and finally the system-wide /etc/ansible/ansible.cfg location.

Understanding the correct ansible cfg file path resolution is essential for maintaining consistent automation behavior across development, staging, and production environments. The lookup logic implemented in the ansible/ansible repository within lib/ansible/config/manager.py establishes a predictable hierarchy that adapts to different deployment contexts while enforcing critical security boundaries against world-writable directories.

Configuration File Precedence Order

According to the source code in lib/ansible/config/manager.py, Ansible builds a candidate list of configuration file locations and selects the first existing, readable file. The resolution follows this exact priority:

1. ANSIBLE_CONFIG Environment Variable

The highest priority location is specified by the ANSIBLE_CONFIG environment variable, read via os.getenv("ANSIBLE_CONFIG") in the configuration manager. If this variable points to a directory, Ansible automatically appends ansible.cfg to the path (lines 64-68).

export ANSIBLE_CONFIG=/opt/ansible/production.cfg
ansible-playbook site.yml

2. Current Working Directory

Ansible checks for ./ansible.cfg in the current working directory. However, if the directory permissions indicate it is world-writable (stat.S_IWOTH), Ansible skips this location and emits a security warning (lines 300-308 of manager.py).

# Valid project directory

cat > ansible.cfg <<'EOF'
[defaults]
inventory = inventory/
remote_user = ubuntu
EOF
ansible-playbook deploy.yml

3. User Home Directory

If no higher-priority configuration exists, Ansible falls back to ~/.ansible.cfg in the user's home directory. This location applies user-specific defaults across all projects.

cat > ~/.ansible.cfg <<'EOF'
[defaults]
forks = 20
host_key_checking = False
EOF

4. System-Wide Location

The final fallback is the hard-coded system path /etc/ansible/ansible.cfg, which requires administrative privileges to modify and affects all system users.

sudo tee /etc/ansible/ansible.cfg > /dev/null <<'EOF'
[defaults]
retry_files_enabled = False
EOF

Security Behavior in World-Writable Directories

Ansible deliberately ignores ansible.cfg files located in world-writable directories to prevent malicious configuration injection. When the current working directory has permissions allowing write access to others (detected via stat.S_IWOTH), the configuration manager skips the local file and proceeds to the next candidate location while logging a warning.

mkdir -p /tmp/shared_project
chmod 777 /tmp/shared_project
cd /tmp/shared_project
echo "[defaults]" > ansible.cfg  # This file will be ignored

ansible-playbook -i inventory.yml play.yml

# Warning emitted: ansible.cfg in world-writable directory is ignored

# Falls back to ~/.ansible.cfg or /etc/ansible/ansible.cfg

Configuring Ansible Across Environments

Development: Project-Local Configuration

For individual projects, place an ansible.cfg file in the repository root. Since Ansible checks the current working directory second in the precedence chain, this ensures environment-specific settings travel with the codebase.

cd /path/to/project
cat > ansible.cfg <<'EOF'
[defaults]
inventory = inventories/development
vault_password_file = .vault_pass
EOF

ansible-playbook playbooks/web.yml

CI/CD Pipelines: Environment Variable Override

In automated pipelines where the working directory may vary or be ephemeral, explicitly set ANSIBLE_CONFIG to ensure consistent behavior regardless of checkout location.

# In CI configuration

export ANSIBLE_CONFIG="${WORKSPACE}/configs/ci-ansible.cfg"
ansible-playbook tests/integration.yml

Shared Systems: User and Global Defaults

On shared bastion hosts or jump servers, configure ~/.ansible.cfg for personal preferences while maintaining system-wide security policies in /etc/ansible/ansible.cfg.

# User-specific optimizations

cat > ~/.ansible.cfg <<'EOF'
[defaults]
callback_enabled = timer, profile_roles
stdout_callback = yaml
EOF

# System-wide security hardening (requires sudo)

sudo tee /etc/ansible/ansible.cfg > /dev/null <<'EOF'
[defaults]
nocows = True
transport = ssh
EOF

Summary

• Ansible CFG file path resolution follows a strict four-tier hierarchy: ANSIBLE_CONFIG environment variable → current working directory → user home directory (~/.ansible.cfg) → system-wide path (/etc/ansible/ansible.cfg).
• The configuration logic in lib/ansible/config/manager.py automatically appends ansible.cfg when ANSIBLE_CONFIG points to a directory.
• World-writable directories trigger a security bypass that ignores local ansible.cfg files to prevent configuration tampering.
• The first existing, readable file in the precedence chain wins; if none exist, Ansible proceeds with built-in defaults.

Frequently Asked Questions

What is the highest priority location for the ansible cfg file path?

The ANSIBLE_CONFIG environment variable always takes precedence. When this variable is set, Ansible uses its value directly (appending ansible.cfg if it points to a directory) and skips all other locations, making it ideal for CI/CD pipelines and temporary overrides.

Why does Ansible ignore ansible.cfg in world-writable directories?

Ansible checks directory permissions using stat.S_IWOTH and skips ansible.cfg files in world-writable directories to prevent security vulnerabilities where malicious actors could inject harmful configuration options into shared directories. This behavior is hard-coded in lib/ansible/config/manager.py lines 300-308.

Can ANSIBLE_CONFIG point to a directory instead of a file?

Yes. If the ANSIBLE_CONFIG environment variable specifies a directory path rather than a file, the configuration manager automatically appends ansible.cfg to that path (as implemented in lines 64-68 of manager.py), allowing you to specify configuration directories while maintaining consistent filenames.

What happens if no ansible.cfg file exists in any location?

If Ansible cannot locate a configuration file in any of the four precedence locations, it proceeds with built-in default values. No error is thrown; the automation simply uses hard-coded defaults for all configuration parameters unless explicitly overridden by command-line flags or environment variables.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}