Ansible Ping Module: Test Host Connectivity & Availability (Guide)

By Luca Berton · Published 2024-01-01 · Category: installation

How to test host availability with Ansible ping module. Verify SSH connectivity, Python interpreter, and troubleshoot unreachable hosts with examples.

Ansible Ping Module: Test Host Connectivity & Availability (Guide)

Ansible module ping. Today we’re going to talk about the simplest way to test if a managed host is available to receive our commands.

Ansible module ping

Today we’re talking about Ansible module ping. The full name is ansible.builtin.ping, which means that is part of the collection of modules “builtin” with ansible and shipped with it. It’s a module pretty stable and out for years. It verify the ability of Ansible to login to the managed host and that there is a Python interpreter that is able to execute our code. So it’s pretty different for the ping in the network context. It's the Linux corresponding to the Ansible win_ping module.

Main parameters and return values

data _string_

People usually don’t specify any parameters or use the return value. For the parameter, it’s possible to change the behavior from the default “pong” to the “crash” that raises an exception in case of failure.

ping _string_

The return value default is the “pong” string, but you could customize it with the data parameter.

Demo

Are you ready to make your hands dirty? Let’s jump in a quick live Playbook of a playbook about the ping module.

---
- name: ping module Playbook
  hosts: all
  become: false
  tasks:
    - name: test connection
      ansible.builtin.ping:

code with ❤️ in GitHub

Conclusion

Now you know better the Ansible module ping and you could use it successfully in your playbook.

What ansible.builtin.ping Actually Does

Despite its name, the Ansible ping module does NOT perform an ICMP ping (like the ping command in your terminal). Instead, it:

Connects to the managed host via SSH (or WinRM for Windows)
Verifies that Python is installed and working
Returns pong on success

This makes it the perfect first test after setting up Ansible to verify your entire connection chain works.

Usage Examples

Ad-hoc command (most common)

# Ping all hosts in inventory
ansible all -m ping -i inventory

# Ping a specific group
ansible webservers -m ping -i inventory

# Ping a single host
ansible 192.168.1.100 -m ping -i inventory

# With specific user and SSH key
ansible all -m ping -i inventory -u devops --private-key=~/.ssh/id_rsa

Expected output (success)

server1 | SUCCESS => {
    "changed": false,
    "ping": "pong"
}

Expected output (failure)

server1 | UNREACHABLE! => {
    "changed": false,
    "msg": "Failed to connect to the host via ssh: Permission denied",
    "unreachable": true
}

In a playbook

---
- name: Verify all hosts are reachable
  hosts: all
  gather_facts: false  # ping doesn't need facts
  tasks:
    - name: test connection
      ansible.builtin.ping:
      register: ping_result

    - name: show result
      ansible.builtin.debug:
        var: ping_result

Ping vs Win_ping

Module	Target OS	Connection	Tests
`ansible.builtin.ping`	Linux/macOS	SSH	SSH + Python
`ansible.windows.win_ping`	Windows	WinRM	WinRM + PowerShell

Troubleshooting Failed Pings

Problem: `UNREACHABLE`

The SSH connection itself failed. Check:

Can you ssh user@host manually?
Is the correct SSH key configured?
Is the correct user specified?

Problem: `MODULE FAILURE` with Python error

SSH works but Python isn't installed or found:

# Install Python on the target
ssh user@host 'sudo apt install python3'  # Debian/Ubuntu
ssh user@host 'sudo yum install python3'  # RHEL/CentOS

Or tell Ansible where Python is:

# inventory
[servers]
host1 ansible_python_interpreter=/usr/bin/python3

Problem: Ping works but playbooks fail

ping only tests basic connectivity. If playbooks fail:

Check become permissions for privileged tasks
Verify gather_facts works: ansible all -m setup -i inventory

FAQ

Should I use `ping` in production playbooks?

Generally no — it's a diagnostic tool. Your playbook tasks will fail naturally if a host is unreachable. Use wait_for_connection instead for orchestration:

- name: Wait for host to come online
  ansible.builtin.wait_for_connection:
    timeout: 300

Can I use ping without an inventory file?

Yes, for quick tests:

ansible all -m ping -i "192.168.1.100,"  # Note the trailing comma!

What's the `data` parameter for?

You can change the return value from pong to anything:

ansible all -m ping -a "data=hello" -i inventory
# Returns: {"ping": "hello"}

Use data=crash to test error handling:

ansible all -m ping -a "data=crash" -i inventory
# Raises an exception

Basic Ping

# Ping all hosts
ansible all -m ping

# Ping specific group
ansible webservers -m ping

# Ping single host
ansible web1 -m ping

Expected Output

web1 | SUCCESS => {
    "changed": false,
    "ping": "pong"
}

Ping with Custom Data

- name: Ping with custom response
  ansible.builtin.ping:
    data: "alive"
  # Returns: "ping": "alive"

In Playbooks

- hosts: all
  gather_facts: false  # Skip facts for faster check
  tasks:
    - name: Verify connectivity
      ansible.builtin.ping:

    - name: Continue with tasks...
      debug: msg="Host {{ inventory_hostname }} is reachable"

Wait for Host

- name: Wait for host to come online
  ansible.builtin.wait_for_connection:
    delay: 10
    timeout: 300

- name: Then verify
  ansible.builtin.ping:

Check Multiple Groups

- hosts: all
  gather_facts: false
  tasks:
    - ping:
      register: ping_result

- hosts: localhost
  tasks:
    - debug:
        msg: "Unreachable: {{ groups['all'] | difference(ansible_play_hosts_all) }}"

Windows Ping

ansible windows_hosts -m win_ping

- ansible.windows.win_ping:
  register: win_result

Troubleshooting Failed Pings

# Verbose output
ansible web1 -m ping -vvvv

# Common issues:
# 1. SSH connection refused → check SSH service
# 2. Authentication failed → check user/key
# 3. Python not found → set ansible_python_interpreter
# 4. Timeout → check network/firewall

# Fix Python interpreter
web1:
  ansible_host: 192.168.1.10
  ansible_python_interpreter: /usr/bin/python3
  # Or auto-detect
  ansible_python_interpreter: auto_silent

ping vs wait_for vs wait_for_connection

Module	What it Tests	Use Case
`ping`	SSH + Python	Basic connectivity
`wait_for`	TCP port	Service availability
`wait_for_connection`	SSH ready	Post-reboot
`uri`	HTTP endpoint	Application health

Health Check Pattern

- hosts: all
  gather_facts: false
  tasks:
    - ping:
      ignore_unreachable: true
      register: ping_result

    - group_by:
        key: "{{ 'reachable' if ping_result is succeeded else 'unreachable' }}"

- hosts: reachable
  tasks:
    - debug: msg="Proceeding with reachable hosts"

FAQ

Does ping use ICMP?

No — Ansible ping connects via SSH (or WinRM) and runs a small Python script. It's NOT an ICMP ping. For ICMP, use command: ping -c 1 host.

Why does ping fail but SSH works?

Usually Python is missing or the wrong version. Set ansible_python_interpreter in your inventory.

Can I ping without an inventory?

ansible all -i "192.168.1.10," -m ping -u deploy
# Note the trailing comma — makes it a list

AnsiblePilot — Master Ansible Automation

Popular Topics

About Luca Berton

Ansible Ping Module: Test Host Connectivity & Availability (Guide)

Ansible module ping

Main parameters and return values

Demo

Conclusion

What ansible.builtin.ping Actually Does

Usage Examples

Ad-hoc command (most common)

Expected output (success)

Expected output (failure)

In a playbook

Ping vs Win_ping

Troubleshooting Failed Pings

Problem: UNREACHABLE

Problem: MODULE FAILURE with Python error

Problem: Ping works but playbooks fail

FAQ

Should I use ping in production playbooks?

Can I use ping without an inventory file?

What's the data parameter for?

Basic Ping

Expected Output

Ping with Custom Data

In Playbooks

Wait for Host

Check Multiple Groups

Windows Ping

Troubleshooting Failed Pings

ping vs wait_for vs wait_for_connection

Health Check Pattern

FAQ

Does ping use ICMP?

Why does ping fail but SSH works?

Can I ping without an inventory?

Related Articles

See also

Problem: `UNREACHABLE`

Problem: `MODULE FAILURE` with Python error

Should I use `ping` in production playbooks?

What's the `data` parameter for?