Pure-pcapy3

Common errors

• ModuleNotFoundError: No module named 'pure_pcapy3'

  cause Attempting to import the library using its package name instead of the exposed `pcapy` module.
  fix Install `pure-pcapy3` using `pip install pure-pcapy3`, then use `import pcapy` in your Python code.

• pcapy.PcapError: Can't open device eth0: eth0: No such device exists (errno 19)

  cause The specified network interface does not exist, or the user lacks permissions to open it, or the underlying `libpcap`/`WinPcap` library is not installed or configured correctly.
  fix Verify the interface name is correct for your system (e.g., `wlan0`, `en0`, `lo`). Ensure `libpcap` (Linux/macOS) or `Npcap` (Windows) is installed. Run your script with appropriate permissions (e.g., `sudo python your_script.py` or add your user to the `wireshark` group).

• pcapy.PcapError: Can't open device eth0: You don't have permission to capture on that device (errno 1)

  cause The user account running the Python script does not have the necessary privileges to open a network interface for packet capture.
  fix On Linux, try running the script with `sudo` (`sudo python your_script.py`), or add your user to the `wireshark` or `pcap` group. On Windows, ensure you are running as an administrator or that `Npcap` is correctly installed with the necessary permissions.

Warnings

• gotcha The package `pure-pcapy3` must be imported as `import pcapy`. This is by design, as it aims to be a drop-in replacement for the original `pcapy` library. Importing `pure_pcapy3` directly will not expose the expected API.
  Fix: Always use `import pcapy` after installing `pure-pcapy3`. Do not attempt `import pure_pcapy3` or `from pure_pcapy3 import pcapy`.
• gotcha Despite being a 'pure Python' implementation, `pure-pcapy3` still relies on an underlying packet capture library (like `libpcap` on Linux/macOS or `WinPcap`/`Npcap` on Windows) to open network interfaces for live capture. These system-level libraries must be installed on your operating system for `pcapy.open_live()` to function correctly.
  Fix: Ensure `libpcap` development headers are installed on Linux/macOS (e.g., `apt-get install libpcap-dev`) or `Npcap` (with 'WinPcap API-compatible mode') on Windows. You may also need appropriate user permissions (e.g., run as root/administrator or add user to `wireshark`/`pcap` group) to capture traffic.
• gotcha Performance of `pure-pcapy3` might be lower than the original C-extension-based `pcapy` or other optimized packet capture libraries for high-throughput scenarios, due to its pure Python nature. If performance is critical, consider the original `pcapy` (if compatible) or alternatives like `scapy` or `dpkt` combined with `pylibpcap`.
  Fix: Benchmark your application with `pure-pcapy3` under expected load. If performance bottlenecks are identified, evaluate whether the pure Python requirement is strict or if a faster, potentially C-dependent, alternative can be used.

Install

• pip install pure-pcapy3 Install pure-pcapy3

Imports

• pcapy
  wrong:

  from pure_pcapy3 import pcapy

  correct:

  import pcapy

  Despite the package name `pure-pcapy3`, the library is designed as a drop-in replacement for `pcapy` and exposes its API directly under the `pcapy` module name. Attempting to import `pure_pcapy3` directly will result in a `ModuleNotFoundError` for the expected API functions.

Quickstart

This quickstart demonstrates how to initialize `pure-pcapy3` for live packet capture on a specified network interface. It includes a basic packet handler and a fallback mechanism to illustrate opening a pcap file. Remember to replace `'eth0'` with an actual network interface on your system (e.g., `'wlan0'`, `'en0'`) and ensure your user has permissions to capture packets (e.g., by running with `sudo` or being in the appropriate user group).

import pcapy
import sys

def packet_handler(header, data):
    # This is a very basic handler. Real-world usage would parse 'data'.
    print(f"Captured packet! Length: {header.getlen()} bytes")

# Try to open 'eth0' or 'en0' (common interface names)
# Fallback to an example pcap file if live capture fails or is not desired.
interface = 'eth0' # Change to your network interface, e.g., 'wlan0', 'en0'
try:
    # Open live capture on a network interface
    # interface, snaplen, promiscuous_mode, timeout_ms
    pc = pcapy.open_live(interface, 1500, True, 100)
    print(f"Listening on interface: {interface}...")
    print("Press Ctrl+C to stop.")
    pc.loop(0, packet_handler) # 0 for infinite loop
except pcapy.PcapError as e:
    print(f"Error opening live capture on {interface}: {e}")
    print("Trying to open a dummy pcap file instead.")
    # Fallback to a dummy pcap file for demonstration if live capture fails
    # (e.g., no permissions, interface not found)
    try:
        # For a runnable example without requiring live interface access, you'd usually have a .pcap file.
        # This example assumes you might have 'test.pcap' or similar.
        # If not, this part will also fail.
        # Create a dummy pcap file if it doesn't exist for the example:
        import os
        dummy_pcap_path = 'dummy.pcap'
        if not os.path.exists(dummy_pcap_path):
            print(f"Warning: '{dummy_pcap_path}' not found. Cannot demonstrate file reading.")
        else:
            print(f"Opening pcap file: {dummy_pcap_path}")
            pc_file = pcapy.open_offline(dummy_pcap_path)
            pc_file.loop(0, packet_handler)
    except pcapy.PcapError as e_file:
        print(f"Error opening pcap file '{dummy_pcap_path}': {e_file}")
        print("Please ensure you have necessary permissions or a valid pcap file.")
except KeyboardInterrupt:
    print("Capture stopped by user.")
except Exception as e:
    print(f"An unexpected error occurred: {e}")