Registry / http-networking / ping3
library5.1.5pypypi✓ verified 22d ago

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.

pip install ping3
INSTALL
IMPORT
SIG · PING3
P
ping3
http-networkingpythonv5.1.5
Install
1.5s avg
Import
41ms
Disk
16MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v5.1.5 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.042s · 17.9MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 1.5s · import 0.040s · 18MB
16MB installed
● package 16MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

ping
from ping3 import ping
verbose_ping
from ping3 import verbose_ping
errors
from ping3 import errors
For access to specific exception types like errors.Timeout, errors.HostUnknown.

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.

import ping3 import os # By default, ping() returns False on HostUnknown and None on Timeout. # For more detailed error handling, set ping3.EXCEPTIONS = True. ping3.EXCEPTIONS = True try: # Ping a well-known host delay = ping3.ping("example.com", timeout=2) if delay is not None: # delay can be 0.0 (fast) or actual time print(f"Ping to example.com: {delay:.2f} seconds") else: print("Ping to example.com failed (no reply).") # Example of an unknown host (will raise HostUnknown with EXCEPTIONS=True) # ping3.ping("not.exist.com") # Example with a very short TTL (might raise TimeToLiveExpired) # ping3.ping("example.com", ttl=1) except ping3.errors.Timeout: print("Ping timed out.") except ping3.errors.HostUnknown: print("Host unknown or could not be resolved.") except ping3.errors.TimeToEndLiveExpired as e: # Catch specific error with new attributes print(f"Time to live expired. Source: {e.ip_header.get('src_addr', 'N/A')}") except ping3.errors.PingError as e: # Catch all other ping3-specific errors print(f"An ICMP ping error occurred: {e}") except OSError as e: # This often indicates permission issues for raw sockets on non-Linux systems or without capabilities. print(f"OS error during ping: {e}. You might need root privileges or specific capabilities.") print("On Linux, try: sudo setcap cap_net_raw+ep $(eval readlink -f $(which python))")
Debug
Known issues
breakingCommand-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.
fix
Review the `ping3 --help` output or documentation for the updated command-line options and adjust scripts accordingly.
affects: >=3.0.0
gotchaUsing `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.
fix
Run your script with `sudo` or configure `CAP_NET_RAW` capabilities for your Python interpreter on Linux.
affects: all
gotchaBy 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()`.
fix
Set `ping3.EXCEPTIONS = True` and wrap your `ping()` calls in `try...except ping3.errors.SomeError:` blocks.
affects: all
gotchaStarting 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.
fix
Update error handling logic to optionally check for and utilize the new `ip_header` and `icmp_header` attributes on relevant exception objects.
affects: >=4.0.0
gotchaWhile `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.
fix
Implement robust concurrency control (e.g., locks) or consider alternative approaches like a process pool if encountering inconsistencies in multithreaded environments.
affects: all
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'ping3'
The 'ping3' module is not installed in the Python environment.
fix
Install the 'ping3' module using the command: pip install ping3
PermissionError: [Errno 1] Operation not permitted
Sending ICMP packets requires administrative privileges.
fix
Run the script with elevated privileges (e.g., using 'sudo' on Unix systems) or configure the system to allow non-root users to send ICMP packets.
ping('example.com') returns None
The ping request timed out, possibly due to network issues or the target host being unreachable.
fix
Check the network connection and ensure the target host is reachable. Adjust the timeout parameter if necessary.
ping('not.exist.com') returns False
The hostname could not be resolved, indicating it does not exist.
fix
Verify the hostname for correctness or use a valid hostname.
ping('example.com', ttl=1) returns None
The Time-To-Live (TTL) value is too low, causing the packet to expire before reaching the destination.
fix
Increase the TTL value to allow the packet to reach the target host.
Upgrade
Version history
5.1.5latest on PyPI · released Aug 10, 2025
Audit
Dependencies

No dependency data recorded yet.

Agent activity
6 hits · last 30 days
node
4
Amazon
1
Resources
ping3 — pip install ping3 · libregistry