{"id":7631,"library":"python-pcapng","title":"Python pcap-ng Library","description":"Python-pcapng is a pure-Python library designed to read and write the pcap-ng file format, which is an evolution of the traditional pcap format used by packet sniffers like Wireshark and tcpdump. It is currently at version 2.1.1 and has an active development cycle, with the last release in August 2022. The library focuses on parsing and generating pcap-ng files, providing a programmatic way to interact with these capture files where other tools might fall short.","status":"active","version":"2.1.1","language":"en","source_language":"en","source_url":"https://github.com/rshk/python-pcapng","tags":["network","pcap","pcap-ng","packet capture","wireshark","parsing","networking"],"install":[{"cmd":"pip install python-pcapng","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Runtime dependency, specifically requires Python >=3.5.","package":"python","optional":false}],"imports":[{"note":"While FileScanner is in pcapng.scanner, it's typically imported directly from the top-level 'pcapng' package for convenience, as shown in official examples.","wrong":"from pcapng.scanner import FileScanner","symbol":"FileScanner","correct":"from pcapng import FileScanner"},{"note":"Used for writing pcap-ng files.","symbol":"FileWriter","correct":"from pcapng.writer import FileWriter"},{"note":"Essential for creating or identifying the start of a pcap-ng file section.","symbol":"SectionHeaderBlock","correct":"from pcapng.blocks import SectionHeaderBlock"}],"quickstart":{"code":"import io\nfrom pcapng import FileScanner\n\n# For demonstration, simulate a pcap-ng file in memory\ndummy_pcapng_data = b'\\n\\r\\r\\n\\x1a\\x2b\\x3c\\x4d\\x00\\x00\\x00\\x00\\x1c\\x00\\x00\\x00\\x01\\x00\\x00\\x00\\xff\\xff\\xff\\xff\\xff\\xff\\xff\\xff\\x1c\\x00\\x00\\x00'\n# This is a minimal, invalid SHB; a real file would be much larger and structured.\n# For a proper example, generate a file using the library's writing capabilities.\n\ntry:\n    with io.BytesIO(dummy_pcapng_data) as fp:\n        scanner = FileScanner(fp)\n        for block in scanner:\n            print(f\"Found block: {type(block).__name__}, Length: {block.block_len}\")\n            # You can access block attributes here, e.g., block.options, block.timestamp\nexcept Exception as e:\n    print(f\"Error reading dummy pcap-ng: {e}\")\n    print(\"Note: The dummy_pcapng_data is highly simplified and likely incomplete for full parsing.\")\n    print(\"For a functional example, use a real pcap-ng file or generate one using FileWriter.\")","lang":"python","description":"The primary use case for `python-pcapng` is to read and parse existing pcap-ng files. This quickstart demonstrates how to open a file-like object and iterate through its blocks using `FileScanner`. Each `block` object will be an instance of a specific pcap-ng block type, allowing access to its parsed data. To handle actual network traffic, replace `io.BytesIO` with `open('your_capture.pcapng', 'rb')`."},"warnings":[{"fix":"Upgrade to `python-pcapng` version 2.0.0 or newer: `pip install --upgrade python-pcapng`.","message":"Write support was introduced in version 2.0.0. Previous versions (pre-2.0.0) were strictly read-only. Attempting to use writing functionalities in older versions will result in `NotImplementedError` or `AttributeError`.","severity":"breaking","affected_versions":"<2.0.0"},{"fix":"Ensure your input file is in the pcap-ng format (`.pcapng`). If you need to read `.pcap` files, use a different library designed for that format (e.g., `scapy`, `dpkt`).","message":"This library is designed exclusively for the **pcap-ng** file format. Attempting to open an older **pcap** file (the original libpcap format, typically `.pcap`) will raise a `ValueError` because it will not start with a valid pcap-ng Section Header Block magic number.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For performance-critical applications, consider wrapping the logic in Cython or using libraries with C-bindings. For typical analysis tasks, the pure Python version is often sufficient. Profile your application to identify bottlenecks.","message":"The library is a pure Python implementation, which can be significantly slower than C-based alternatives for large-scale packet processing or high-performance scenarios. The maintainer acknowledges this trade-off for ease of development in Python.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If you intentionally need to create 'marginal' pcap-ng files (e.g., for testing other parsers), you can adjust the strictness using `from pcapng.strictness import set_strictness, Strictness; set_strictness(Strictness.WARN)` or `Strictness.NONE`.","message":"When writing pcap-ng files, the library operates with a 'strictness' setting, defaulting to `Strictness.FORBID`. This prevents the creation of malformed or non-compliant pcap-ng structures by raising exceptions on invalid operations (e.g., adding multiple non-repeatable options).","severity":"gotcha","affected_versions":"All versions with write support (>=2.0.0)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Verify that your input file is indeed in the pcap-ng format. If it's a `.pcap` file, convert it to pcap-ng using a tool like Wireshark/editcap or use a different Python library capable of reading `.pcap` (e.g., `scapy`).","cause":"Attempting to open a classic `.pcap` file using `python-pcapng`, which only supports the `.pcapng` format.","error":"ValueError: File not starting with a proper section header"},{"fix":"Ensure you install the correct package: `pip uninstall pcapng` (if installed) then `pip install python-pcapng`.","cause":"Incorrect package installation. Users often mistakenly install `pcapng` (a different, unrelated library) instead of `python-pcapng`.","error":"ModuleNotFoundError: No module named 'pcapng'"},{"fix":"After retrieving the `packet_data` from an `EnhancedPacketBlock` (or `SimplePacketBlock`), use a dedicated network protocol parsing library (e.g., `scapy`, `dpkt`, `pyshark`) to interpret the byte payload. For example, `from scapy.all import Ether; ether_frame = Ether(block.packet_data)`.","cause":"The `python-pcapng` library parses the *pcap-ng file structure* and provides access to raw packet data. It does *not* automatically parse higher-level network protocols (like Ethernet, IP, TCP/UDP payloads) within the packet data itself.","error":"AttributeError: 'EnhancedPacketBlock' object has no attribute 'payload' (or similar for higher-layer protocols)"}]}