{"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":"python","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,"search_vec":"'3.0.4':5 '3.7':59 'activ':32 'api':39 'async':66 'asynchron':38 'build':18 'compat':45 'cross':43 'cross-platform':42 'current':3 'depend':29 'design':11 'develop':33 'easili':13 'extern':28 'forg':14 'icmp':15,63 'icmplib':1,2 'ipv4':53 'ipv6':55 'later':61 'librari':10 'like':21 'linux':47 'maco':48 'network':19,62 'offer':34 'packet':16 'ping':22,64 'platform':44 'provid':41 'pure':8 'python':9,58 'reli':26 'requir':57 'socket':67 'support':51 'synchron':36 'tool':20 'tracerout':24,65 'version':4 'window':50 'without':25","created_at":"2026-04-14T05:06:30.439863+00:00","updated_at":"2026-04-16T15:40:49.229942+00:00","problems":[{"fix":"Install the library using pip: `pip install icmplib` or `pip3 install icmplib`.","cause":"The 'icmplib' library has not been installed in the Python environment currently being used.","error":"ModuleNotFoundError: No module named 'icmplib'"},{"fix":"Run the Python script with `sudo` (e.g., `sudo python your_script.py`). Alternatively, you can allow the Python executable to manipulate raw network packets without `sudo` by setting file capabilities: `sudo setcap cap_net_raw+ep $(realpath $(which python3))` (this affects all Python scripts). For `ping` and `multiping` functions, you might be able to use `privileged=False` (e.g., `ping('1.1.1.1', privileged=False)`) if your OS kernel is configured to handle ICMP headers in unprivileged mode (e.g., by setting `sudo sysctl -w net.ipv4.ping_group_range='0 2147483647'` on Linux), though this may not be suitable for `traceroute`.","cause":"On Unix-like systems (Linux, macOS), creating raw ICMP sockets typically requires root privileges, which the current user lacks.","error":"icmplib.exceptions.SocketPermissionError: Root privileges are required to create the socket"},{"fix":"Run the Python script or your IDE as an administrator. Ensure that no firewall rules are blocking the application from creating raw sockets.","cause":"On Windows, creating raw sockets for ICMP operations often requires administrator privileges, or the attempt might be blocked by firewall or security software.","error":"OSError: [WinError 10013] An attempt was made to access a socket in a way forbidden by its access permissions."},{"fix":"Verify that the hostname or FQDN is spelled correctly and is reachable on the network. Ensure your system's DNS settings are correct. Consider using an IP address directly instead of a hostname if the issue persists.","cause":"The hostname or Fully Qualified Domain Name (FQDN) provided to an `icmplib` function could not be resolved to an IP address by the system's DNS resolver.","error":"icmplib.exceptions.NameLookupError: The requested name does not exist or cannot be resolved"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"3.0.4","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/ValentinBELYN/icmplib","docs":null,"changelog":null,"pypi":"https://pypi.org/project/icmplib/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["http-networking"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-31","next_check":"2026-07-28","install_tag":null}}