ping3

5.1.5 · active · verified Sun Apr 12

ping3 is a pure Python3 library for implementing ICMP ping using raw sockets. It provides a straightforward API to send ICMP echo requests and receive replies, with support for both IPv4 and IPv6, and robust error handling. The library is actively maintained with a regular release cadence, ensuring ongoing compatibility and feature enhancements.

Warnings

breaking Command-line arguments changed significantly in v3.0.0. For example, `-w`/`--wait` became `-t`/`--timeout`, and `-t`/`--ttl` became `-T`/`--ttl`. This affects users invoking `ping3` from the command line, requiring updates to scripts or manual commands.
Fix: Review the `ping3 --help` output or documentation for the updated command-line options and adjust scripts accordingly.
gotcha Using `ping3` typically requires root privileges (e.g., `sudo`) on most operating systems to create raw sockets. On Linux, it's possible to grant `CAP_NET_RAW` capability to the Python executable to run without `sudo` (e.g., `sudo setcap cap_net_raw+ep $(eval readlink -f $(which python))`). Version 2.9.0 introduced support for root-less pings on Linux with appropriate capabilities set.
Fix: Run your script with `sudo` or configure `CAP_NET_RAW` capabilities for your Python interpreter on Linux.
gotcha By default, `ping3.ping()` returns `False` for `HostUnknown` and `None` for `Timeout`. To raise specific `ping3.errors` exceptions (e.g., `ping3.errors.Timeout`, `ping3.errors.HostUnknown`) for more granular error handling, you must explicitly set `ping3.EXCEPTIONS = True` prior to calling `ping()`.
Fix: Set `ping3.EXCEPTIONS = True` and wrap your `ping()` calls in `try...except ping3.errors.SomeError:` blocks.
gotcha Starting from `v4.0.0`, error objects for `TimeToLiveExpired`, `DestinationUnreachable`, and `DestinationHostUnreachable` exceptions include `ip_header` and `icmp_header` attributes, providing more detailed information. Code directly accessing or assuming the absence of these attributes on older versions might behave differently or break if upgraded without considering these additions.
Fix: Update error handling logic to optionally check for and utilize the new `ip_header` and `icmp_header` attributes on relevant exception objects.
gotcha While `ping3` can be used in multithreaded applications, there have been historical reports (e.g., GitHub Issue #26) of potential issues or wrong results when using the library concurrently. Thorough testing is recommended for concurrent `ping3` usage.
Fix: Implement robust concurrency control (e.g., locks) or consider alternative approaches like a process pool if encountering inconsistencies in multithreaded environments.

Install

pip install ping3 Install ping3

Imports

ping
```
from ping3 import ping
```
verbose_ping
```
from ping3 import verbose_ping
```
errors
```
from ping3 import errors
```
For access to specific exception types like errors.Timeout, errors.HostUnknown.

Quickstart

This quickstart demonstrates basic ICMP ping functionality using `ping3.ping()`. It includes best practices for robust error handling by enabling `ping3.EXCEPTIONS = True` and catching various `ping3.errors` subclasses. It also highlights common `OSError`s related to raw socket permissions.

import ping3
import os

# By default, ping() returns False on HostUnknown and None on Timeout.
# For more detailed error handling, set ping3.EXCEPTIONS = True.
ping3.EXCEPTIONS = True

try:
    # Ping a well-known host
    delay = ping3.ping("example.com", timeout=2)
    if delay is not None: # delay can be 0.0 (fast) or actual time
        print(f"Ping to example.com: {delay:.2f} seconds")
    else:
        print("Ping to example.com failed (no reply).")

    # Example of an unknown host (will raise HostUnknown with EXCEPTIONS=True)
    # ping3.ping("not.exist.com")

    # Example with a very short TTL (might raise TimeToLiveExpired)
    # ping3.ping("example.com", ttl=1)

except ping3.errors.Timeout:
    print("Ping timed out.")
except ping3.errors.HostUnknown:
    print("Host unknown or could not be resolved.")
except ping3.errors.TimeToEndLiveExpired as e: # Catch specific error with new attributes
    print(f"Time to live expired. Source: {e.ip_header.get('src_addr', 'N/A')}")
except ping3.errors.PingError as e: # Catch all other ping3-specific errors
    print(f"An ICMP ping error occurred: {e}")
except OSError as e:
    # This often indicates permission issues for raw sockets on non-Linux systems or without capabilities.
    print(f"OS error during ping: {e}. You might need root privileges or specific capabilities.")
    print("On Linux, try: sudo setcap cap_net_raw+ep $(eval readlink -f $(which python))")

view raw JSON →