{"id":10069,"library":"pure-pcapy3","title":"Pure-pcapy3","description":"pure-pcapy3, currently at version 1.0.1, is a pure Python reimplementation of the `pcapy` library, designed to be API compatible and a drop-in replacement. It allows Python programs to capture live network traffic and read/write pcap files without requiring C extensions. While aiming for full compatibility, its release cadence is infrequent, focusing on stability.","status":"active","version":"1.0.1","language":"en","source_language":"en","source_url":"https://github.com/pure-pcapy/pure-pcapy3","tags":["networking","pcap","packet capture","pcapy","network security","pure python"],"install":[{"cmd":"pip install pure-pcapy3","lang":"bash","label":"Install pure-pcapy3"}],"dependencies":[],"imports":[{"note":"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.","wrong":"from pure_pcapy3 import pcapy","symbol":"pcapy","correct":"import pcapy"}],"quickstart":{"code":"import pcapy\nimport sys\n\ndef packet_handler(header, data):\n    # This is a very basic handler. Real-world usage would parse 'data'.\n    print(f\"Captured packet! Length: {header.getlen()} bytes\")\n\n# Try to open 'eth0' or 'en0' (common interface names)\n# Fallback to an example pcap file if live capture fails or is not desired.\ninterface = 'eth0' # Change to your network interface, e.g., 'wlan0', 'en0'\ntry:\n    # Open live capture on a network interface\n    # interface, snaplen, promiscuous_mode, timeout_ms\n    pc = pcapy.open_live(interface, 1500, True, 100)\n    print(f\"Listening on interface: {interface}...\")\n    print(\"Press Ctrl+C to stop.\")\n    pc.loop(0, packet_handler) # 0 for infinite loop\nexcept pcapy.PcapError as e:\n    print(f\"Error opening live capture on {interface}: {e}\")\n    print(\"Trying to open a dummy pcap file instead.\")\n    # Fallback to a dummy pcap file for demonstration if live capture fails\n    # (e.g., no permissions, interface not found)\n    try:\n        # For a runnable example without requiring live interface access, you'd usually have a .pcap file.\n        # This example assumes you might have 'test.pcap' or similar.\n        # If not, this part will also fail.\n        # Create a dummy pcap file if it doesn't exist for the example:\n        import os\n        dummy_pcap_path = 'dummy.pcap'\n        if not os.path.exists(dummy_pcap_path):\n            print(f\"Warning: '{dummy_pcap_path}' not found. Cannot demonstrate file reading.\")\n        else:\n            print(f\"Opening pcap file: {dummy_pcap_path}\")\n            pc_file = pcapy.open_offline(dummy_pcap_path)\n            pc_file.loop(0, packet_handler)\n    except pcapy.PcapError as e_file:\n        print(f\"Error opening pcap file '{dummy_pcap_path}': {e_file}\")\n        print(\"Please ensure you have necessary permissions or a valid pcap file.\")\nexcept KeyboardInterrupt:\n    print(\"Capture stopped by user.\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"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)."},"warnings":[{"fix":"Always use `import pcapy` after installing `pure-pcapy3`. Do not attempt `import pure_pcapy3` or `from pure_pcapy3 import pcapy`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Install `pure-pcapy3` using `pip install pure-pcapy3`, then use `import pcapy` in your Python code.","cause":"Attempting to import the library using its package name instead of the exposed `pcapy` module.","error":"ModuleNotFoundError: No module named 'pure_pcapy3'"},{"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).","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.","error":"pcapy.PcapError: Can't open device eth0: eth0: No such device exists (errno 19)"},{"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.","cause":"The user account running the Python script does not have the necessary privileges to open a network interface for packet capture.","error":"pcapy.PcapError: Can't open device eth0: You don't have permission to capture on that device (errno 1)"}]}