{"id":4684,"library":"ping3","title":"ping3","description":"ping3 is a pure Python3 library for implementing ICMP ping using raw sockets. It provides a straightforward API to send ICMP echo requests and receive replies, with support for both IPv4 and IPv6, and robust error handling. The library is actively maintained with a regular release cadence, ensuring ongoing compatibility and feature enhancements.","status":"active","version":"5.1.5","language":"en","source_language":"en","source_url":"https://github.com/kyan001/ping3","tags":["network","ping","icmp","raw-sockets","utility","ipv4","ipv6"],"install":[{"cmd":"pip install ping3","lang":"bash","label":"Install ping3"}],"dependencies":[],"imports":[{"symbol":"ping","correct":"from ping3 import ping"},{"symbol":"verbose_ping","correct":"from ping3 import verbose_ping"},{"note":"For access to specific exception types like errors.Timeout, errors.HostUnknown.","symbol":"errors","correct":"from ping3 import errors"}],"quickstart":{"code":"import ping3\nimport os\n\n# By default, ping() returns False on HostUnknown and None on Timeout.\n# For more detailed error handling, set ping3.EXCEPTIONS = True.\nping3.EXCEPTIONS = True\n\ntry:\n    # Ping a well-known host\n    delay = ping3.ping(\"example.com\", timeout=2)\n    if delay is not None: # delay can be 0.0 (fast) or actual time\n        print(f\"Ping to example.com: {delay:.2f} seconds\")\n    else:\n        print(\"Ping to example.com failed (no reply).\")\n\n    # Example of an unknown host (will raise HostUnknown with EXCEPTIONS=True)\n    # ping3.ping(\"not.exist.com\")\n\n    # Example with a very short TTL (might raise TimeToLiveExpired)\n    # ping3.ping(\"example.com\", ttl=1)\n\nexcept ping3.errors.Timeout:\n    print(\"Ping timed out.\")\nexcept ping3.errors.HostUnknown:\n    print(\"Host unknown or could not be resolved.\")\nexcept ping3.errors.TimeToEndLiveExpired as e: # Catch specific error with new attributes\n    print(f\"Time to live expired. Source: {e.ip_header.get('src_addr', 'N/A')}\")\nexcept ping3.errors.PingError as e: # Catch all other ping3-specific errors\n    print(f\"An ICMP ping error occurred: {e}\")\nexcept OSError as e:\n    # This often indicates permission issues for raw sockets on non-Linux systems or without capabilities.\n    print(f\"OS error during ping: {e}. You might need root privileges or specific capabilities.\")\n    print(\"On Linux, try: sudo setcap cap_net_raw+ep $(eval readlink -f $(which python))\")\n","lang":"python","description":"This quickstart demonstrates basic ICMP ping functionality using `ping3.ping()`. It includes best practices for robust error handling by enabling `ping3.EXCEPTIONS = True` and catching various `ping3.errors` subclasses. It also highlights common `OSError`s related to raw socket permissions."},"warnings":[{"fix":"Review the `ping3 --help` output or documentation for the updated command-line options and adjust scripts accordingly.","message":"Command-line arguments changed significantly in v3.0.0. For example, `-w`/`--wait` became `-t`/`--timeout`, and `-t`/`--ttl` became `-T`/`--ttl`. This affects users invoking `ping3` from the command line, requiring updates to scripts or manual commands.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Run your script with `sudo` or configure `CAP_NET_RAW` capabilities for your Python interpreter on Linux.","message":"Using `ping3` typically requires root privileges (e.g., `sudo`) on most operating systems to create raw sockets. On Linux, it's possible to grant `CAP_NET_RAW` capability to the Python executable to run without `sudo` (e.g., `sudo setcap cap_net_raw+ep $(eval readlink -f $(which python))`). Version 2.9.0 introduced support for root-less pings on Linux with appropriate capabilities set.","severity":"gotcha","affected_versions":"all"},{"fix":"Set `ping3.EXCEPTIONS = True` and wrap your `ping()` calls in `try...except ping3.errors.SomeError:` blocks.","message":"By default, `ping3.ping()` returns `False` for `HostUnknown` and `None` for `Timeout`. To raise specific `ping3.errors` exceptions (e.g., `ping3.errors.Timeout`, `ping3.errors.HostUnknown`) for more granular error handling, you must explicitly set `ping3.EXCEPTIONS = True` prior to calling `ping()`.","severity":"gotcha","affected_versions":"all"},{"fix":"Update error handling logic to optionally check for and utilize the new `ip_header` and `icmp_header` attributes on relevant exception objects.","message":"Starting from `v4.0.0`, error objects for `TimeToLiveExpired`, `DestinationUnreachable`, and `DestinationHostUnreachable` exceptions include `ip_header` and `icmp_header` attributes, providing more detailed information. Code directly accessing or assuming the absence of these attributes on older versions might behave differently or break if upgraded without considering these additions.","severity":"gotcha","affected_versions":">=4.0.0"},{"fix":"Implement robust concurrency control (e.g., locks) or consider alternative approaches like a process pool if encountering inconsistencies in multithreaded environments.","message":"While `ping3` can be used in multithreaded applications, there have been historical reports (e.g., GitHub Issue #26) of potential issues or wrong results when using the library concurrently. Thorough testing is recommended for concurrent `ping3` usage.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}