pyminiping 1.0.1

Pure Python ICMP ping with statistics and hop count

pyminiping

pyminiping is a pure Python ICMP ping library for Linux servers.

It sends one or more ICMP echo packets and provides detailed statistics: min, max, mean, median, jitter, TTL, estimated number of hops, and an OS family guess based on TTL.

Features

• Pure Python ICMP Echo (RAW socket, requires root or CAP_NET_RAW)
• Statistics: min, max, mean, median, jitter (standard deviation)
• Sent/received packet count and loss percentage
• TTL and estimated hop count (hops)
• Operating system family guess (os_guess) based on received TTL
• Customizable parameters: count, timeout, interval, size
• IPv4 and IPv6 supporting
• dscp value (0-63) for traffic prioritization
• Percentile 95

Installation

git clone https://github.com/roxy-wi/pyminiping.git
cd pyminiping
python3 -m pip install .

Example usage

from pyminiping import ping, DestinationUnreachable

try:
    result = ping('8.8.8.8', count=5, timeout=1, interval=0.2)
    print(result)
    print(result.as_dict())
except DestinationUnreachable as e:
    print(f"Unreachable: {e.message} (code {e.code})")
except Exception as e:
    print(f"Ping failed: {e}")

Example Output

PingResult(
    sent=5,
    received=5,
    loss=0.0,
    min=0.0044,
    max=0.0062,
    mean=0.0048,
    median=0.0045,
    jitter=0.0007,
    rtt_list=[0.0062, 0.0044, 0.0045, 0.0044, 0.0045],
    ttl=110,
    hops=19,
    os_guess='Windows',
    p95=0.0007
)

or as dict

{
    'sent': 5,
    'received': 5,
    'loss': 0.0,
    'min': 0.0044,
    'max': 0.0062,
    'mean': 0.0048,
    'median': 0.0045,
    'jitter': 0.0007,
    'rtt_list': [0.0062, 0.0044, 0.0045, 0.0044, 0.0045],
    'ttl': 110,
    'hops': 19,
    'os_guess': 'Windows',
    'p95': 0.0007
}

Command-Line Interface (CLI)

After installing pyminiping, you can use it as a command-line tool.

Option	Description	Default
host	Host to ping (required)
-c, --count	Number of packets to send	4
-t, --timeout	Timeout per packet (seconds)	1
-i, --interval	Interval between packets (seconds, float allowed)	0.1
-s, --size	Payload size in bytes	8
--dscp	DSCP value (0-63, for QoS)	not set

Basic usage

sudo pyminiping 8.8.8.8

Common DSCP values

Name	DSCP	Use Case
Default	0	Best Effort
CS1	8	Background
AF11	10	Low-priority data
AF21	18	Standard
AF41	46	Voice, high-priority
EF	46	Expedited Forwarding

Notes

Requires root privileges or CAP_NET_RAW capability (e.g., sudo python3 yourscript.py)

Linux only (tested on Ubuntu/Debian)

The hop count (hops) is calculated using common initial TTL values (64, 128, 255). For most Linux servers this is accurate.

Troubleshooting RAW socket permissions

• If you see: "Root privileges or CAP_NET_RAW are required to create RAW socket"
  • Run your script as root, e.g. sudo python3 script.py
  • Or, to allow your Python interpreter to use RAW sockets without root:
    • On Linux: sudo setcap cap_net_raw+ep $(readlink -f $(which python3))
  • For more details, see: https://man7.org/linux/man-pages/man7/capabilities.7.html