{"id":5773,"library":"icmplib","title":"icmplib","description":"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.","status":"active","version":"3.0.4","language":"en","source_language":"en","source_url":"https://github.com/ValentinBELYN/icmplib","tags":["network","icmp","ping","traceroute","async","sockets"],"install":[{"cmd":"pip install icmplib","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"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.","wrong":"from icmplib import ping","symbol":"async_ping","correct":"from icmplib import async_ping"},{"symbol":"Host","correct":"from icmplib import Host"},{"symbol":"SocketPermissionError","correct":"from icmplib import SocketPermissionError"}],"quickstart":{"code":"import asyncio\nfrom icmplib import async_ping\n\nasync def check_host(address):\n    try:\n        host = await async_ping(address, count=4, interval=0.2, timeout=2)\n        if host.is_alive:\n            print(f\"{host.address} is UP! Latency: {host.avg_rtt:.2f} ms\")\n        else:\n            print(f\"{host.address} is DOWN.\")\n    except Exception as e:\n        print(f\"Error checking {address}: {e}\")\n\nif __name__ == \"__main__\":\n    target_address = \"example.com\" # Replace with an IP address or hostname\n    asyncio.run(check_host(target_address))","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"When using `icmplib` on Unix-like systems (Linux, macOS), creating raw ICMP sockets often requires root privileges, which can raise a `SocketPermissionError`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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''`.","message":"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`.","severity":"gotcha","affected_versions":">=3.0.2"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}