Ansible Magic Variables: Complete Reference Guide (2026)
By Luca Berton · Published 2024-01-01 · Category: troubleshooting
Complete guide to Ansible magic variables (special variables). hostvars, groups, inventory_hostname, play_hosts, ansible_facts, role_path. Learn every built-in variable with examples.
Ansible Magic Variables: Complete Reference Guide (2026)
Magic variables (special variables) are automatically set by Ansible and available in every playbook. They provide information about hosts, groups, the current play, and the execution environment. This guide covers every important magic variable with practical examples.
Host and Inventory Variables
inventory_hostname
The name of the current host as defined in inventory:
inventory_hostname_short
The short hostname (first part before the dot):
ansible_host
The actual IP/hostname used to connect (may differ from inventory_hostname):
ansible_play_hosts / play_hosts
List of all hosts in the current play that haven't failed:
ansible_play_batch
Hosts in the current batch (affected by serial):
Group Variables
groups
Dictionary of all groups and their hosts:
group_names
List of groups the current host belongs to:
Cross-Host Data Access
hostvars
Access any host's variables from any other host:
Playbook and Play Variables
ansible_playbook_python
Path to the Python interpreter on the controller:
ansible_version
Ansible version information:
playbook_dir
Directory of the current playbook:
role_path
Path of the currently executing role:
ansible_check_mode
Whether running in check (dry-run) mode:
ansible_diff_mode
Whether running with --diff:
Loop Variables
ansible_loop
Extended loop information (requires extended: true):
Available attributes: • ansible_loop.index — 1-based position • ansible_loop.index0 — 0-based position • ansible_loop.first — true on first iteration • ansible_loop.last — true on last iteration • ansible_loop.length — total items • ansible_loop.previtem — previous item • ansible_loop.nextitem — next item
Task and Role Variables
ansible_role_name / role_name
Name of the current role:
ansible_parent_role_names
List of parent roles (for nested role calls):
ansible_run_tags / ansible_skip_tags
Tags applied to the current run:
Connection Variables
ansible_connection
Connection type used:
ansible_user
The remote user for the connection:
Quick Reference Table
| Variable | Returns | Example Value | |----------|---------|---------------| | inventory_hostname | Host name from inventory | web01.example.com | | inventory_hostname_short | Short hostname | web01 | | ansible_host | Connection address | 192.168.1.10 | | groups | All groups → hosts dict | {'webservers': ['web01']} | | group_names | Current host's groups | ['webservers', 'production'] | | hostvars | All hosts' variables | Dict of dicts | | ansible_play_hosts | Active hosts in play | ['web01', 'web02'] | | play_hosts | Same as ansible_play_hosts | ['web01', 'web02'] | | playbook_dir | Playbook directory | /home/user/ansible | | role_path | Current role path | /home/user/roles/nginx | | ansible_version | Ansible version dict | {'full': '2.17.0'} | | ansible_check_mode | Check mode active | true / false | | ansible_diff_mode | Diff mode active | true / false |
FAQ
What are Ansible magic variables?
Magic variables (special variables) are automatically set by Ansible during playbook execution. They provide information about hosts, groups, the play, and the environment without you defining them. Examples include inventory_hostname, groups, hostvars, and ansible_play_hosts.
How do I access another host's variables in Ansible?
Use hostvars: hostvars['other_host']['variable_name']. The target host must be in the inventory, and its facts must be gathered (or the variable must be set in inventory/group_vars).
What is the difference between inventory_hostname and ansible_hostname?
inventory_hostname is the name as defined in your inventory file. ansible_hostname is the actual system hostname gathered from the remote machine via facts. They may differ if your inventory uses aliases or FQDNs.
How do I list all hosts in a group from a playbook?
Use groups['group_name'] to get a list of all hosts in that group. For example: groups['webservers'] returns ['web01', 'web02'].
How do I check if a host is in a specific group?
Use when: "'group_name' in group_names" in your task. The group_names magic variable contains a list of all groups the current host belongs to.
Conclusion
Ansible magic variables give you access to inventory, host, group, and play information without explicit variable definitions. Master hostvars, groups, group_names, and inventory_hostname for dynamic playbooks that adapt to your infrastructure.
Related Articles • Ansible Variables: Complete Guide • Ansible Facts: Gather System Information • Ansible Inventory: Complete Guide • Ansible debug Module: Print Variables & Messages
Category: troubleshooting