Pythonping

1.1.4 · active · verified Thu Apr 16

Pythonping is an active Python library (current version 1.1.4) that provides a simple and modular way to send ICMP probes to remote devices, similar to the `ping` utility available in most operating systems. It allows developers to perform network reachability tests directly from Python scripts, with options to customize packet size, timeout, interval, and collect detailed response statistics. The library maintains a steady release cadence with improvements and bug fixes.

Common errors

```
PermissionError: [Errno 13] Permission denied
```
cause Pythonping uses raw sockets to send ICMP packets, which requires elevated privileges on most operating systems.

fix Run your Python script with `sudo python your_script.py` on Linux/macOS, or execute it from an elevated command prompt/terminal (Run as Administrator) on Windows.
```
ModuleNotFoundError: No module named 'pythonping'
```
cause The `pythonping` library is not installed in the active Python environment, or the script is being run with a different Python interpreter than the one where the library was installed.

fix Install the library using `pip install pythonping`. If using virtual environments, ensure the correct environment is activated. If multiple Python versions are installed, use `python3 -m pip install pythonping` and `python3 your_script.py` to ensure consistency.
```
AttributeError: 'ResponseList' object has no attribute 'packet_loss'
```
cause The `packet_loss` attribute (and later comprehensive `stats_` attributes) was added in version 1.0.15 (and expanded in 1.1.3). This error occurs if you are running an older version of `pythonping`.

fix Upgrade the library to version 1.0.15 or newer to access `packet_loss`, or to 1.1.3 or newer for `stats_packets_sent`, `stats_lost_ratio`, etc. using `pip install --upgrade pythonping`.
```
SyntaxError: invalid syntax (on Python 2.x)
```
cause Pythonping is developed for Python 3.x, and its syntax is not compatible with Python 2.x.

fix Ensure you are running your script with a Python 3 interpreter (e.g., `python3 your_script.py`). Pythonping does not support Python 2.x.

Warnings

breaking Version 1.1.0 introduced the `interval` parameter. If you were previously calling `ping()` with positional arguments for `payload`, `sweep_start`, or `sweep_end`, their positions shifted. It's recommended to use keyword arguments for clarity and future compatibility.
Fix: Update your `ping()` calls to use keyword arguments for `payload`, `sweep_start`, and `sweep_end` (e.g., `ping('host', payload=b'data')` instead of `ping('host', b'data')`).
gotcha Pythonping requires raw socket access to send ICMP packets, which typically demands administrative privileges (root/sudo on Linux/macOS, or an elevated command prompt on Windows). Without these, you will encounter `PermissionError`.
Fix: Run your Python script with `sudo python your_script.py` on Linux/macOS, or execute it from a command prompt/terminal run as Administrator on Windows.
gotcha Prior to version 1.1.4, the `count` parameter was limited to 16-bit values. Attempts to specify a count greater than 65535 would not work as expected.
Fix: Upgrade to version 1.1.4 or higher to use `count` values beyond 16-bit. If on an older version and unable to upgrade, limit `count` to 65535 or less.
gotcha Versions prior to 1.0.14 could experience intermittent failures when used in a threaded environment due to an underlying `socket.getprotobyname()` issue (Python Issue 30482).
Fix: Upgrade to version 1.0.14 or newer to resolve the intermittent threaded usage failures. If upgrading is not possible, implement robust error handling around `ping` calls in threads.

Install

pip install pythonping Install latest version

Imports

ping
```
from pythonping import ping
```

Quickstart

This quickstart pings Google's public DNS server (8.8.8.8) four times, prints detailed output for each response, and then summarizes the session with statistics like packet loss and round-trip times. It includes error handling for common permission issues.

import os
from pythonping import ping

# Ping a common public DNS server (e.g., Google DNS) or a local host.
# Note: Pinging often requires administrative privileges (root/sudo on Linux/macOS, or elevated command prompt on Windows)
# due to raw socket access. If you encounter 'PermissionError', try running your script with appropriate permissions.

try:
    print("\nPinging 8.8.8.8 with 4 packets...")
    response_list = ping('8.8.8.8', count=4, timeout=1, verbose=True)
    
    print("\n--- Ping Results ---")
    for response in response_list:
        if response.is_success:
            print(f"Reply from {response.address}, {response.bytes_received} bytes in {response.time_elapsed:.2f}ms")
        else:
            print(f"Request to {response.address} timed out or failed.")

    # Access statistics available from v1.1.3+
    if hasattr(response_list, 'stats_packets_sent'):
        print(f"\nPackets Sent: {response_list.stats_packets_sent}")
        print(f"Packets Received: {response_list.stats_packets_returned}")
        print(f"Packet Loss Ratio: {response_list.stats_lost_ratio:.2%}")
        print(f"Min RTT: {response_list.rtt_min:.2f}ms, Avg RTT: {response_list.rtt_avg:.2f}ms, Max RTT: {response_list.rtt_max:.2f}ms")

except PermissionError as e:
    print(f"Error: {e}. You might need to run this script with administrative privileges (e.g., sudo on Linux/macOS, or as Administrator on Windows).")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

view raw JSON →