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

Introduction

Ansible is a powerful automation tool used for configuration management, application deployment, and task automation. It simplifies the management of complex infrastructures by allowing users to define tasks in easy-to-understand YAML files. However, to harness its full potential, it’s essential to understand and manage its configuration effectively. This is where the ansible-config command comes into play. In this article, we'll explore the ansible-config tool, its various actions, and how to use it to manage Ansible's configuration.

See also: 10 Proven Methods to Optimize Ansible Playbook Performance

What is ansible-config?

ansible-config is a command-line utility provided by Ansible that allows users to view, manipulate, and manage Ansible's configuration settings. It provides a way to interact with Ansible's configuration files, making it easier to customize and troubleshoot Ansible's behavior.

Links

• https://docs.ansible.com/ansible/latest/cli/ansible-config.html • https://docs.ansible.com/ansible/latest/reference_appendices/config.html

Configuration Files

Ansible looks for configuration files in specific locations; their precedence determines which one is used. Here are the two main configuration files: • /etc/ansible/ansible.cfg: This is the system-wide configuration file used if present. It applies to all users. • ~/.ansible.cfg: This is the user-specific configuration file and takes precedence over the system-wide configuration. It allows users to customize Ansible's behavior for their specific needs. • ansible.cfg: This is the current directory setting for the project.

Environment Variables

Ansible allows you to override default configuration settings using environment variables. The primary environment variable for configuring Ansible is ANSIBLE_CONFIG. You can point Ansible to a specific configuration file by setting this variable.

Example:

export ANSIBLE_CONFIG=/path/to/my/ansible.cfg

See also: Maximize Ansible Efficiency with Callback Plugins for Resource Monitoring

Common Options

Before diving into the actions, let’s understand some common options available with the ansible-config command: • --version: This option displays the program's version number, the location of the configuration file, the configured module search path, module location, executable location, and then exits. • -h, --help: Use this option to display the help message and exit. • -v, --verbose: Increasing verbosity is a useful way to troubleshoot issues. You can add multiple -v options to increase the verbosity level. -vvv is a reasonable starting point, and debugging network connections might require -vvvv.

Actions

The ansible-config command supports various actions, each serving a specific purpose. Here are the available actions:

1. list

The list action allows you to list and output available configuration settings. You can use options like --format to specify the output format, -c to provide a path to a specific configuration file, and -t to filter down to a specific plugin type.

Example:

ansible-config list --format yaml

Output

ACTION_WARNINGS:
  default: true
  description:
  - By default Ansible will issue a warning when received from a task action (module
    or action plugin)
  - These warnings can be silenced by adjusting this setting to False.
  env:
  - name: ANSIBLE_ACTION_WARNINGS
  ini:
  - key: action_warnings
    section: defaults
  name: Toggle action warnings
  type: boolean
  version_added: '2.5'
AGNOSTIC_BECOME_PROMPT:
  default: true
  description: Display an agnostic become prompt instead of displaying a prompt containi>
    the command line supplied become method
  env:
  - name: ANSIBLE_AGNOSTIC_BECOME_PROMPT
  ini:
  - key: agnostic_become_prompt
    section: privilege_escalation
[...]

2. dump

The dump action displays the current configuration settings and merges them with the ansible.cfg file if specified. You can also use the --only-changed option to show configurations that have changed from the default.

Example:

ansible-config dump --only-changed

Output

CALLBACKS_ENABLED(/Users/lberton/prj/gitlab/ansible-pilot/callback/ansible.cfg) = ['ansi>
CONFIG_FILE() = /Users/lberton/prj/gitlab/ansible-pilot/callback/ansible.cfg

3. view

The view action displays the current contents of the configuration file. You can use the -c option to specify a path to a specific configuration file and -t to filter by a specific plugin type.

Example:

ansible-config view

Output

[defaults]
callback_whitelist=ansible.posix.timer,ansible.posix.profile_tasks,ansible.posix.profile>
callbacks_enabled=ansible.posix.timer,ansible.posix.profile_tasks,ansible.posix.profile_>

4. init

The init action is used to create an initial configuration file. You can use the --disabled option to prefix all entries with a comment character to disable them. Additionally, you can specify the output format with --format.

Example:

ansible-config init --disabled --format ini

Output

[defaults]
# (boolean) By default Ansible will issue a warning when received from a task action (mo>
# These warnings can be silenced by adjusting this setting to False.
;action_warnings=True
# (list) Accept list of cowsay templates that are 'safe' to use, set to empty list if yo>
;cowsay_enabled_stencils=bud-frogs, bunny, cheese, daemon, default, dragon, elephant-in->
# (string) Specify a custom cowsay path or swap in your cowsay implementation of choice
;cowpath=
# (string) This allows you to chose a specific cowsay stencil for the banners or use 'ra>
;cow_selection=default
# (boolean) This option forces color mode even when running without a TTY or the "nocolo>
;force_color=False
# (path) The default root path for Ansible config files on the controller.
;home=~/.ansible
# (boolean) This setting allows suppressing colorizing output, which is used to give a b>
;nocolor=False
[...]

See also: Ansible Magic Variables: Complete Reference with Examples

Conclusion

The ansible-config command is a valuable tool for managing Ansible's configuration settings, allowing users to customize their Ansible experience to suit their specific needs. Understanding its various actions and options allows you to gain greater control over Ansible's behavior and streamline your automation tasks. Whether you need to list available configurations, view the current settings, or initialize a new configuration file, ansible-config is your go-to utility for managing Ansible's configuration.

Related Articles

• configuration files via Ansible template • Ansible privilege escalation patterns • environment variables in shell modules of Ansible