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. I’m Luca Berton and welcome to today’s episode of Ansible Pilot.

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.

See also: Add Secondary Groups to Linux Users with Ansible Playbook

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

See also: Ansible Linux Users and Groups: Complete Management Guide (Examples)

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.

See also: Ansible code in RHSB-2021-009 Log4Shell - Remote Code Execution - log4j (CVE-2021-44228)

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

Related Articles

• become and privilege escalation explained • static and dynamic Ansible inventory • desired-state Windows config with Ansible

See also

• Ansible ping Module: Test Host Connectivity (Complete Guide)