Install & Compatibility
Where this runs
tested against v2.1.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.020s · 18MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.6s · import 0.016s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
FileScanner
✓ from pcapng import FileScanner
✗ from pcapng.scanner import FileScanner
While FileScanner is in pcapng.scanner, it's typically imported directly from the top-level 'pcapng' package for convenience, as shown in official examples.
FileWriter
✓ from pcapng.writer import FileWriter
Used for writing pcap-ng files.
SectionHeaderBlock
✓ from pcapng.blocks import SectionHeaderBlock
Essential for creating or identifying the start of a pcap-ng file section.
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')`.
import io
from pcapng import FileScanner
# For demonstration, simulate a pcap-ng file in memory
dummy_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'
# This is a minimal, invalid SHB; a real file would be much larger and structured.
# For a proper example, generate a file using the library's writing capabilities.
try:
with io.BytesIO(dummy_pcapng_data) as fp:
scanner = FileScanner(fp)
for block in scanner:
print(f"Found block: {type(block).__name__}, Length: {block.block_len}")
# You can access block attributes here, e.g., block.options, block.timestamp
except Exception as e:
print(f"Error reading dummy pcap-ng: {e}")
print("Note: The dummy_pcapng_data is highly simplified and likely incomplete for full parsing.")
print("For a functional example, use a real pcap-ng file or generate one using FileWriter.")
Debug
Known issues
breakingWrite 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`.fixUpgrade to `python-pcapng` version 2.0.0 or newer: `pip install --upgrade python-pcapng`.
affects: <2.0.0
gotchaThis 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.fixEnsure 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`).
affects: All versions
gotchaThe 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.fixFor 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.
affects: All versions
gotchaWhen 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).fixIf 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`.
affects: All versions with write support (>=2.0.0)
Errors
Common errors & fixes
ValueError: File not starting with a proper section header
Attempting to open a classic `.pcap` file using `python-pcapng`, which only supports the `.pcapng` format.
fixVerify 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`).
ModuleNotFoundError: No module named 'pcapng'
Incorrect package installation. Users often mistakenly install `pcapng` (a different, unrelated library) instead of `python-pcapng`.
fixEnsure you install the correct package: `pip uninstall pcapng` (if installed) then `pip install python-pcapng`.
AttributeError: 'EnhancedPacketBlock' object has no attribute 'payload' (or similar for higher-layer protocols)
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.
fixAfter 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)`.
Upgrade
Version history
2.1.1latest on PyPI · released Aug 23, 2022
Audit
Dependencies
pythonrequiredRuntime dependency, specifically requires Python >=3.5.