icmplib

3.0.4 · active · verified Tue Apr 14

icmplib (current version 3.0.4) is a pure Python library designed for easily forging ICMP packets and building network tools like ping and traceroute without relying on external dependencies. It is actively developed, offering both synchronous and asynchronous APIs, and provides cross-platform compatibility for Linux, macOS, and Windows, supporting both IPv4 and IPv6. It requires Python 3.7 or later.

Warnings

breaking Version 3.0.0 introduced a significant breaking change by making the library primarily asynchronous. All core functions like `ping`, `multiping`, and `traceroute` were rewritten to be non-blocking.
Fix: Migrate synchronous code using `ping`, `multiping`, or `traceroute` to their `async_` counterparts (e.g., `async_ping`) and run them within an `asyncio` event loop.
gotcha When using `icmplib` on Unix-like systems (Linux, macOS), creating raw ICMP sockets often requires root privileges, which can raise a `SocketPermissionError`.
Fix: Run your Python script with `sudo` (e.g., `sudo python your_script.py`) or initialize sockets with `privileged=False` if your operating system configuration allows unprivileged ICMP sockets. The `ping`, `multiping`, and `traceroute` functions accept a `privileged` parameter.
breaking Version 2.0.0 introduced a 'new library architecture' and changed how the library handles root privileges, adding the ability to use it without root privileges by setting the `privileged` parameter.
Fix: Review existing code written for 1.x to ensure compatibility with the new architecture and explicitly handle the `privileged` parameter if non-root operation is desired.
gotcha As of version 3.0.2, the `payload` property of an `ICMPRequest` object now returns a random value if the payload is not explicitly defined, instead of `None`.
Fix: If your application relies on `payload` being `None` when not set, adjust your logic to check for explicitly empty payloads or handle random data. To define an empty payload, set `payload=b''`.

Install

pip install icmplib Install latest version

Imports

async_ping
```
from icmplib import async_ping
```
As of v3.0.0, the library is primarily asynchronous. The `ping` function is still available but rewritten and now defaults to an asynchronous implementation if not explicitly called from an async context. For new async projects, `async_ping` is the recommended entry point.
Host
```
from icmplib import Host
```

SocketPermissionError

from icmplib import SocketPermissionError

Quickstart

This example demonstrates how to perform an asynchronous ICMP ping to a target address and report its status and average round-trip time. It uses the `async_ping` function, which is the recommended way to interact with the library since version 3.0.0.

import asyncio
from icmplib import async_ping

async def check_host(address):
    try:
        host = await async_ping(address, count=4, interval=0.2, timeout=2)
        if host.is_alive:
            print(f"{host.address} is UP! Latency: {host.avg_rtt:.2f} ms")
        else:
            print(f"{host.address} is DOWN.")
    except Exception as e:
        print(f"Error checking {address}: {e}")

if __name__ == "__main__":
    target_address = "example.com" # Replace with an IP address or hostname
    asyncio.run(check_host(target_address))

view raw JSON →