{"id":10121,"library":"pypcap","title":"pypcap","description":"pypcap is a Python interface to the `libpcap` C library, enabling programmatic packet capture and analysis. It provides access to network devices and allows reading packets from live captures or pcap dump files. The current version is 1.3.0. Releases are infrequent but address Python compatibility and underlying `libpcap` features.","status":"active","version":"1.3.0","language":"en","source_language":"en","source_url":"https://github.com/pynetwork/pypcap","tags":["network","packet capture","libpcap","networking","raw socket"],"install":[{"cmd":"pip install pypcap","lang":"bash","label":"Install pypcap"},{"cmd":"sudo apt-get install libpcap-dev python3-dev\npip install pypcap","lang":"bash","label":"Install on Debian/Ubuntu (with libpcap)"},{"cmd":"sudo yum install libpcap-devel python3-devel\npip install pypcap","lang":"bash","label":"Install on Fedora/CentOS (with libpcap)"},{"cmd":"brew install libpcap\npip install pypcap","lang":"bash","label":"Install on macOS (with libpcap)"}],"dependencies":[],"imports":[{"symbol":"pcap","correct":"import pcap"}],"quickstart":{"code":"import pcap\nimport os\nimport sys\n\ntry:\n    # Try to find a default network device\n    dev = pcap.lookupdev()\n    if dev is None:\n        print(\"No default network device found. Attempting to list all devices...\")\n        all_devs = pcap.findalldevs()\n        if not all_devs:\n            print(\"No network devices available on this system.\")\n            sys.exit(1)\n        dev = all_devs[0] # Use the first available device as a fallback\n        print(f\"Using first available device: {dev}\")\n\n    # Allow overriding the device from an environment variable for easier testing\n    capture_device = os.environ.get('PCAP_DEV', dev)\n\n    print(f\"Attempting to capture on device: {capture_device}\")\n\n    pc = pcap.pcap(capture_device)\n    # Optional: Set a BPF filter (e.g., 'tcp port 80' or 'udp')\n    # pc.setfilter('tcp')\n\n    print(\"Starting packet capture (press Ctrl+C to stop)...\")\n    for ts, pkt in pc:\n        # ts is the timestamp (float), pkt is the raw packet bytes\n        print(f\"[{ts}] Captured packet of length: {len(pkt)} bytes\")\n        # For detailed parsing, consider libraries like scapy or dpkt\n\nexcept pcap.PcapError as e:\n    print(f\"Error initializing pcap: {e}\")\n    print(\"\\nCommon issues:\\n1. Lack of permissions: Try running with `sudo` (e.g., `sudo python your_script.py`).\\n2. Device not found: Check if '{capture_device}' is the correct interface name (use `pcap.findalldevs()` to list).\\\n3. `libpcap` not installed: Ensure `libpcap-dev` (Linux) or `libpcap` (macOS) is installed.\")\n    sys.exit(1)\nexcept KeyboardInterrupt:\n    print(\"\\nCapture stopped by user.\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\n    sys.exit(1)","lang":"python","description":"This quickstart captures packets on a default or specified network interface. It includes error handling for common issues like permissions and device availability. Run with `sudo` on Linux/macOS for best results."},"warnings":[{"fix":"Install `libpcap-dev` on Debian/Ubuntu (`sudo apt-get install libpcap-dev`), `libpcap-devel` on RHEL/CentOS (`sudo yum install libpcap-devel`), or `libpcap` on macOS (`brew install libpcap`).","message":"pypcap is a wrapper around the C library `libpcap`. You must have `libpcap` development headers installed on your system for `pypcap` to build and run correctly.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Run your Python script with `sudo` (e.g., `sudo python your_script.py`) or configure `setcap` on Linux to grant `cap_net_raw,cap_net_admin` capabilities to your Python executable.","message":"Capturing raw network packets typically requires elevated privileges (e.g., root/administrator) due to security restrictions on accessing network interfaces directly.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For Python 3 projects, ensure `pypcap` is version 1.2.0 or higher. If you must use Python 2, ensure `pypcap` is below 1.2.0.","message":"Python 3 support was introduced in version 1.2.0. Versions prior to 1.2.0 are Python 2 exclusive and will not work with Python 3 interpreters.","severity":"breaking","affected_versions":"<1.2.0"},{"fix":"Upgrade `pypcap` to version 1.2.0 or higher to ensure correct and reliable packet iteration behavior.","message":"An iteration bug affecting `for ts, pkt in pc:` loops was fixed in version 1.2.0, potentially leading to incorrect or incomplete packet sequences in older versions.","severity":"gotcha","affected_versions":"<1.2.0"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Ensure `libpcap` development headers are installed on your system (e.g., `sudo apt-get install libpcap-dev` for Debian/Ubuntu) and then reinstall `pypcap` (`pip install pypcap`). Verify you are running the script in the same environment where `pypcap` was installed.","cause":"`libpcap` development headers are missing, preventing the `pcap` Python module from being compiled and installed correctly, or the Python environment is not configured to find the installed module.","error":"ImportError: No module named pcap"},{"fix":"Run the script with root privileges (`sudo python your_script.py`). Alternatively, on Linux, you can grant `cap_net_raw,cap_net_admin` capabilities to your Python executable using `sudo setcap cap_net_raw,cap_net_admin=eip $(eval readlink -f $(which python))`.","cause":"The Python script lacks the necessary permissions to open and capture packets on the specified network interface.","error":"pcap.PcapError: eth0: Permission denied"},{"fix":"Use `pcap.findalldevs()` to list all available network interfaces on your system and choose the correct one (e.g., 'en0', 'wlan0', 'Wi-Fi').","cause":"The network interface name specified (e.g., 'eth0') does not exist or is misspelled on your system.","error":"pcap.PcapError: eth0: No such device (pcap_activate: eth0: No such device)"},{"fix":"Ensure you are using a modern `pypcap` version (1.2.0+) which fully supports iteration (`for ts, pkt in pc:`). If the error persists, consult the `pypcap` GitHub repository for API usage or upgrade to the latest stable release.","cause":"Attempting to iterate over a `pcap` object in a way that is not supported by the installed `pypcap` version, often due to using a very old version or misuse of the API.","error":"TypeError: 'Pcap' object is not iterable"}]}