Special Variables — Ansible Documentation

- AnsibleFest
- Products
- Community
- Webinars & Training
- Blog

Documentation

# Special Variables

## Magic

These variables cannot be set directly by the user; Ansible will always override them to reflect internal state.

ansible_check_mode
  Boolean that indicates if we are in check mode or not
ansible_dependent_role_names
  The names of the roles currently imported into the current play as dependencies of other plays
ansible_diff_mode
  Boolean that indicates if we are in diff mode or not
ansible_forks
  Integer reflecting the number of maximum forks available to this run
ansible_inventory_sources
  List of sources used as inventory
ansible_limit
  Contents of the `--limit` CLI option for the current execution of Ansible
ansible_loop
  A dictionary/map containing extended loop information when enabled via `loop_control.extended`
ansible_loop_var
  The name of the value provided to `loop_control.loop_var`. Added in `2.8`
ansible_play_batch
  List of active hosts in the current play run limited by the serial, aka ‘batch’. Failed/Unreachable hosts are not considered ‘active’.
ansible_play_hosts
  The same as ansible_play_batch
ansible_play_hosts_all
  List of all the hosts that were targeted by the play
ansible_play_role_names
  The names of the roles currently imported into the current play. This list does not contain the role names that are implicitly included via dependencies.
ansible_playbook_python
  The path to the python interpreter being used by Ansible on the controller
ansible_role_names
  The names of the roles currently imported into the current play, or roles referenced as dependencies of the roles imported into the current play.
ansible_run_tags
  Contents of the `--tags` CLI option, which specifies which tags will be included for the current run.
ansible_search_path
  Current search path for action plugins and lookups, i.e where we search for relative paths when you do `template: src=myfile`
ansible_skip_tags
  Contents of the `--skip_tags` CLI option, which specifies which tags will be skipped for the current run.
ansible_verbosity
  Current verbosity setting for Ansible
ansible_version
  Dictionary/map that contains information about the current running version of ansible, it has the following keys: full, major, minor, revision and string.
group_names
  List of groups the current host is part of
groups
  A dictionary/map with all the groups in inventory and each group has the list of hosts that belong to it
hostvars
  A dictionary/map with all the hosts in inventory and variables assigned to them
inventory_hostname
  The inventory name for the ‘current’ host being iterated over in the play
inventory_hostname_short
  The short version of inventory_hostname
inventory_dir
  The directory of the inventory source in which the inventory_hostname was first defined
inventory_file
  The file name of the inventory source in which the inventory_hostname was first defined
omit
  Special variable that allows you to ‘omit’ an option in a task, i.e `- user: name=bob home={{ bobs_home|default(omit) }}`
play_hosts
  Deprecated, the same as ansible_play_batch
ansible_play_name
  The name of the currently executed play. Added in `2.8`.
playbook_dir
  The path to the directory of the playbook that was passed to the `ansible-playbook` command line.
role_name
  The name of the currently executed role
role_names
  Deprecated, the same as ansible_play_role_names
role_path
  The path to the dir of the currently running role

## Facts

These are variables that contain information pertinent to the current host (inventory_hostname). They are only available if gathered first.

ansible_facts
  Contains any facts gathered or cached for the inventory_hostname Facts are normally gathered by the setup module automatically in a play, but any module can return facts.
ansible_local
  Contains any ‘local facts’ gathered or cached for the inventory_hostname. The keys available depend on the custom facts created. See the setup module for more details.

## Connection variables

Connection variables are normally used to set the specifics on how to execute actions on a target. Most of them correspond to connection plugins, but not all are specific to them; other plugins like shell, terminal and become are normally involved. Only the common ones are described as each connection/become/shell/etc plugin can define its own overrides and specific variables.

ansible_become_user
  The user Ansible ‘becomes’ after using privilege escalation. This must be available to the ‘login user’.
ansible_connection
  The connection plugin actually used for the task on the target host.
ansible_host
  The ip/name of the target host to use instead of inventory_hostname.
ansible_python_interpreter
  The path to the Python executable Ansible should use on the target host.
ansible_user
  The user Ansible ‘logs in’ as.