MultiPing Library

Common errors

• OSError: [Errno 1] Operation not permitted

  cause The Python process does not have the necessary permissions to create raw sockets required for sending ICMP packets.
  fix Run the script with elevated privileges: `sudo python your_script.py` on Linux/macOS, or as an administrator on Windows. Ensure no firewall is blocking outbound ICMP traffic.

• socket.error: [Errno 1] Operation not permitted

  cause Same as `OSError`, indicates insufficient permissions to perform raw socket operations.
  fix Run the script with elevated privileges: `sudo python your_script.py` on Linux/macOS, or as an administrator on Windows. Check firewall rules.

• ModuleNotFoundError: No module named 'multiping'

  cause The `multiping` library has not been installed in the current Python environment, or the environment is not active.
  fix Install the library using pip: `pip install multiping`. If using a virtual environment, ensure it is activated before installation and execution.

Warnings

• gotcha Sending raw ICMP packets often requires elevated privileges (root on Linux/macOS, administrator on Windows). Without them, you will likely encounter `PermissionError` or `OSError: [Errno 1] Operation not permitted`.
  Fix: Run your Python script with `sudo python your_script.py` on Linux/macOS, or as an administrator on Windows. Alternatively, consider using `setcap` on Linux to grant CAP_NET_RAW capability to your Python executable if appropriate for your security model.
• gotcha The `receive()` method blocks for the specified timeout, collecting responses. If the timeout is too short, you might miss late responses. If it's too long, your program might wait unnecessarily.
  Fix: Choose an appropriate timeout value for `mp.receive(timeout_seconds)` based on your network conditions and requirements. A typical starting point is 0.5 to 1.0 seconds for general internet hosts.
• gotcha Resolving hostnames (e.g., 'google.com') occurs synchronously when `MultiPing` is initialized. If you have many hostnames or slow DNS servers, this can delay the start of pinging. Unresolvable hostnames will lead to them being silently dropped from the list of hosts to ping.
  Fix: For critical applications or a large number of hosts, pre-resolve hostnames to IP addresses using `socket.gethostbyname()` or similar functions before passing them to `MultiPing`. Handle DNS resolution errors explicitly if required.

Install

• pip install multiping Install stable release

Imports

• MultiPing

  from multiping import MultiPing

Quickstart

This quickstart demonstrates how to initialize `MultiPing` with a list of hosts, send ICMP echo requests, and then receive responses within a specified timeout. It handles common `PermissionError` that arises from sending raw ICMP packets.

from multiping import MultiPing
import time

# List of hosts to ping
hosts = ['127.0.0.1', 'google.com', 'nonexistent.domain', '8.8.8.8']

try:
    # Create a MultiPing instance with a list of hosts
    # Optionally specify a port (defaults to 1 for ICMP) and IPv6 (False by default)
    mp = MultiPing(hosts, timeout=1, retry=1, verbose=False)

    # Send the ICMP echo requests
    # This sends packets in a non-blocking way
    mp.send()

    # Wait for responses for up to 1 second
    # receive() returns responses, and a list of hosts that did not respond within the timeout
    responses, no_responses = mp.receive(1.0)

    print("--- Ping Results ---")
    for addr, rtt in responses.items():
        print(f"Host: {addr}, RTT: {rtt*1000:.2f} ms")

    if no_responses:
        print("\n--- No Response From ---")
        for addr in no_responses:
            print(f"Host: {addr}")

except PermissionError:
    print("Error: Permission denied. Running ping often requires root/administrator privileges.")
    print("Try running with 'sudo python your_script.py' or as an administrator on Windows.")
except Exception as e:
    print(f"An unexpected error occurred: {e}")