Ansible debug Module: Print Variables & Messages (Complete Guide)
By Luca Berton · Published 2024-01-01 · Category: troubleshooting
How to use the Ansible debug module (ansible.builtin.debug) to print variables, messages, and registered output. Debug playbooks with msg, var, and verbosity.
Ansible debug Module: Print Variables & Messages (Complete Guide)
The Ansible debug module (ansible.builtin.debug) prints variables, messages, and expressions during playbook execution. It's the primary tool for inspecting data and troubleshooting automation.
See also: Ansible debug vs assert: When to Use Each Module
Basic Usage
Print a Message
---
- name: Debug module examples
hosts: all
tasks:
- name: Print a simple message
ansible.builtin.debug:
msg: "Hello from {{ inventory_hostname }}"Print a Variable
- name: Print a variable
ansible.builtin.debug:
var: ansible_distribution
# Output:
# ok: [server1] => {
# "ansible_distribution": "Ubuntu"
# }Parameters
| Parameter | Description | Example |
|---|---|---|
msg | Message to print (supports Jinja2) | "Host: {{ inventory_hostname }}" |
var | Variable name to print (no {{ }} needed) | ansible_os_family |
verbosity | Only show at this verbosity level or higher | 2 (needs -vv) |
msg or var, not both.
See also: Ansible debug Module: Print Variables & Debug Messages (Complete Guide)
Print Registered Output
- name: Run a command
ansible.builtin.command: df -h /
register: disk_usage
changed_when: false
- name: Print full registered variable
ansible.builtin.debug:
var: disk_usage
- name: Print just stdout
ansible.builtin.debug:
var: disk_usage.stdout
- name: Print stdout lines
ansible.builtin.debug:
var: disk_usage.stdout_lines
- name: Print return code
ansible.builtin.debug:
msg: "Command returned: {{ disk_usage.rc }}"Print Complex Data Structures
Dictionaries
- name: Print dictionary
ansible.builtin.debug:
var: ansible_default_ipv4
- name: Print specific key
ansible.builtin.debug:
msg: "IP: {{ ansible_default_ipv4.address }}, Gateway: {{ ansible_default_ipv4.gateway }}"Lists
- name: Print all mounts
ansible.builtin.debug:
var: ansible_mounts
- name: Print first mount point
ansible.builtin.debug:
msg: "First mount: {{ ansible_mounts[0].mount }}"
- name: Print all mount points
ansible.builtin.debug:
msg: "{{ ansible_mounts | map(attribute='mount') | list }}"See also: Ansible Debug Module: Print Variables & Messages During Playbook Execution
Conditional Debug Output
- name: Warn if disk is almost full
ansible.builtin.debug:
msg: "WARNING: {{ item.mount }} is {{ item.size_available }} bytes free"
loop: "{{ ansible_mounts }}"
when: item.size_available < 1073741824 # Less than 1GB
- name: Debug only on specific hosts
ansible.builtin.debug:
msg: "This host runs {{ ansible_distribution }} {{ ansible_distribution_version }}"
when: ansible_os_family == "Debian"Verbosity Levels
Control when debug output appears:
- name: Always visible (default)
ansible.builtin.debug:
msg: "This always prints"
- name: Only with -v
ansible.builtin.debug:
msg: "Verbose output"
verbosity: 1
- name: Only with -vv
ansible.builtin.debug:
msg: "Very verbose: {{ hostvars[inventory_hostname] }}"
verbosity: 2
- name: Only with -vvv
ansible.builtin.debug:
msg: "Extra verbose debug data"
verbosity: 3Run with: ansible-playbook playbook.yml -vv
Print Facts and Magic Variables
- name: Gather facts and print useful info
hosts: all
tasks:
- name: OS information
ansible.builtin.debug:
msg: |
Hostname: {{ ansible_hostname }}
FQDN: {{ ansible_fqdn }}
OS: {{ ansible_distribution }} {{ ansible_distribution_version }}
Kernel: {{ ansible_kernel }}
Architecture: {{ ansible_architecture }}
CPUs: {{ ansible_processor_vcpus }}
Memory: {{ ansible_memtotal_mb }} MB
IP: {{ ansible_default_ipv4.address | default('N/A') }}
- name: Print all ansible facts
ansible.builtin.debug:
var: ansible_facts
verbosity: 2Print Loop Items
- name: Debug each package status
ansible.builtin.debug:
msg: "Package {{ item.item }} is {{ item.state | default('unknown') }}"
loop: "{{ package_results.results }}"
when: package_results is defined
- name: Print with loop index
ansible.builtin.debug:
msg: "{{ ansible_loop.index }}: {{ item }}"
loop:
- nginx
- postgresql
- redis
loop_control:
extended: trueFormat Output with Filters
- name: Pretty-print JSON
ansible.builtin.debug:
msg: "{{ some_dict | to_nice_json }}"
- name: Print as YAML
ansible.builtin.debug:
msg: "{{ some_dict | to_nice_yaml }}"
- name: Print variable type
ansible.builtin.debug:
msg: "Type of my_var: {{ my_var | type_debug }}"
- name: Print length of list
ansible.builtin.debug:
msg: "Number of servers: {{ server_list | length }}"Debug Patterns
Assert-then-debug
- name: Validate and show configuration
block:
- name: Assert required variables
ansible.builtin.assert:
that:
- db_host is defined
- db_port is defined
fail_msg: "Missing database configuration"
- name: Show resolved config
ansible.builtin.debug:
msg: "Connecting to {{ db_host }}:{{ db_port }}"
rescue:
- name: Debug available variables
ansible.builtin.debug:
msg: "db_host={{ db_host | default('UNDEFINED') }}, db_port={{ db_port | default('UNDEFINED') }}"Pause-style debugging
- name: Show info and wait for confirmation
ansible.builtin.debug:
msg: |
About to deploy to: {{ inventory_hostname }}
Environment: {{ env_name }}
Version: {{ app_version }}
- name: Confirm before continuing
ansible.builtin.pause:
prompt: "Press Enter to continue or Ctrl+C to abort"msg vs var
# var: prints variable name and value (no Jinja2 braces needed)
- ansible.builtin.debug:
var: ansible_hostname
# Output: "ansible_hostname": "web01"
# msg: prints formatted message (Jinja2 expressions supported)
- ansible.builtin.debug:
msg: "Host is {{ ansible_hostname }}"
# Output: "msg": "Host is web01"
# var with attributes
- ansible.builtin.debug:
var: result.stdout_lines[0]FAQ
What is the Ansible debug module used for?
The ansible.builtin.debug module prints messages and variable values during playbook execution. It's the primary way to inspect data, troubleshoot errors, and verify variable content in Ansible automation.
How do I print a variable in Ansible?
Use ansible.builtin.debug with var: variable_name (no curly braces) or msg: "{{ variable_name }}". The var parameter shows the raw variable; msg allows formatted output with Jinja2 expressions.
What is the difference between debug msg and var?
msg accepts a string with Jinja2 expressions ("Value: {{ my_var }}") and prints a formatted message. var takes a raw variable name (my_var) and prints both the name and value. Use msg for formatted output, var for quick inspection.
How do I debug only at higher verbosity?
Set the verbosity parameter: verbosity: 2 makes the task output only visible when running with -vv or higher. This keeps normal output clean while preserving debug info for troubleshooting.
How do I print registered command output?
Register the task result, then use debug with var: result.stdout for text output, var: result.stdout_lines for line-by-line, or var: result for the full result object including return code and stderr.
Conclusion
The Ansible debug module is essential for playbook development and troubleshooting. Use var for quick variable inspection, msg for formatted output, and verbosity to control when debug info appears. Combine with register, when, and loops for targeted debugging.
Related Articles
Category: troubleshooting