# Ansible CFG File Path: Configuration Location Precedence in Different Environments

> Discover the ansible cfg file path precedence: ANSIBLE_CONFIG env variable, current directory, user home, and system-wide locations. Master Ansible configuration.

- Repository: [Ansible/ansible](https://github.com/ansible/ansible)
- Tags: how-to-guide
- Published: 2026-02-21

---

**Ansible resolves the [`ansible.cfg`](https://github.com/ansible/ansible/blob/main/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`](https://github.com/ansible/ansible/blob/main//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`](https://github.com/ansible/ansible/blob/main/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`](https://github.com/ansible/ansible/blob/main/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`](https://github.com/ansible/ansible/blob/main/ansible.cfg) to the path (lines 64-68).

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

```

### 2. Current Working Directory

Ansible checks for [`./ansible.cfg`](https://github.com/ansible/ansible/blob/main/./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`](https://github.com/ansible/ansible/blob/main/manager.py)).

```bash

# 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.

```bash
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`](https://github.com/ansible/ansible/blob/main//etc/ansible/ansible.cfg), which requires administrative privileges to modify and affects all system users.

```bash
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`](https://github.com/ansible/ansible/blob/main/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.

```bash
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`](https://github.com/ansible/ansible/blob/main/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.

```bash
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.

```bash

# 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`](https://github.com/ansible/ansible/blob/main//etc/ansible/ansible.cfg).

```bash

# 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`](https://github.com/ansible/ansible/blob/main//etc/ansible/ansible.cfg)).
- The configuration logic in [`lib/ansible/config/manager.py`](https://github.com/ansible/ansible/blob/main/lib/ansible/config/manager.py) automatically appends [`ansible.cfg`](https://github.com/ansible/ansible/blob/main/ansible.cfg) when `ANSIBLE_CONFIG` points to a directory.
- World-writable directories trigger a security bypass that ignores local [`ansible.cfg`](https://github.com/ansible/ansible/blob/main/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`](https://github.com/ansible/ansible/blob/main/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`](https://github.com/ansible/ansible/blob/main/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`](https://github.com/ansible/ansible/blob/main/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`](https://github.com/ansible/ansible/blob/main/ansible.cfg) to that path (as implemented in lines 64-68 of [`manager.py`](https://github.com/ansible/ansible/blob/main/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.