Ansible debug Module: Print Variables & Messages (Complete Guide)

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) |

Note: Use either 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: 3

Run 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: 2

Print 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: true

Format 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

• Ansible Troubleshooting: Debug & Fix Playbook Errors • Ansible register: Capture Task Output • Ansible assert Module: Validate Variables & Conditions