Low-level implementations of common networking protocols, in pure Python with zero dependencies.

Decode raw header bytes into typed, immutable protocol objects — or build those objects from field values and serialize them back to their exact on-wire form. Every header is a frozen dataclass whose fields mirror the wire format, so decoded traffic is introspectable, comparable, and round-trippable.

>>> from netprotocols import Ethernet
>>> eth = Ethernet.decode(frame)
>>> eth
Ethernet(dst='ff:ff:ff:ff:ff:ff', src='00:07:0d:af:f4:54', ethertype=2054)
>>> eth.ethertype_name
'ARP'
>>> eth.next_protocol()
<class 'netprotocols.layer2.arp.ARP'>
>>> bytes(eth) == frame[:eth.header_len]
True

Every header is also a structural pattern — no extra code, because a frozen dataclass auto-generates __match_args__ and every enum field is an IntEnum, so a bare wire value matches a named one:

match ip:
    case IPv4(protocol=IPProtocol.TCP, ttl=t) if t > 32:
        ...
    case IPv4(protocol=IPProtocol.UDP):
        ...

pip install netprotocols

Requires Python 3.12+. Fully typed (py.typed, mypy strict).

Measured against dpkt 1.9.8 and scapy 2.8.0 on the 411 frames of real captured traffic the corpus holds at 2.9.0 (CPython 3.12.12, x86-64 Linux; re-measured for 2.9.0 on 2026-11-06 — see docs/CLAIMS.md for every number below, its reproduction command, and its caveats):

• 3.0× faster than scapy on decode; dpkt is 1.5× faster — uv run --group bench python scripts/benchmark.py --compare. dpkt is the faster of the two comparators. The routing captures 2.5.0 added (OSPF, BGP, PIM, RIP, VRRP) are where it pulls ahead, taking about three fifths of netprotocols' time on them. On the 140 frames the corpus held at 2.4.0 dpkt is ahead by a median 1.21× across runs. On the MPLS and LLC/SNAP captures 2.6.0 added they are level; dpkt leaves LLDP undecoded, so it is about 5× faster on those six frames, and it stops at UDP (at TCP for STUN's two TCP segments) on the TFTP, RADIUS, STUN, NTP and HSRP captures 2.7.0 added, where it is about 1.5× faster, and at TCP on the TLS capture 2.8.0 added, where it is about 2× faster. Those per-capture figures were measured for 2.8.0 and not repeated for 2.9.0. Narrowing the gap is #250. The gap moves both ways as this library and dpkt each change, and this file's job is to say so honestly rather than only when it's flattering.
• Decodes further into the stack than dpkt on 175 of those 411 frames — BGP, RIP, LLDP, DNS, DHCP, NTP, RADIUS, STUN, HSRP, TFTP, TLS and VXLAN-tunnelled payloads that dpkt leaves as raw bytes (dpkt ships decoders for several of them, but its UDP and TCP never dispatch on a port), and 802.1Q tags, MPLS label stacks and SNAP headers it folds into the Ethernet and LLC headers, netprotocols decodes as layers of their own. A throughput number means little without knowing how much work it bought.
• 1.35× faster than dpkt at re-encoding a whole Ethernet/IPv4/UDP frame (bytes(packet) against bytes(dpkt.ethernet.Ethernet(frame)), scripts/benchmark_encode.py) — the other half of "codec" that nobody else benchmarks.
• Imports in 54 ms; scapy.all takes about 227 ms (scripts/benchmark_import.py, with cached bytecode, as after pip install or after the first import; the first import after a source checkout compiles its modules and takes longer), and never touches the host doing it — importing scapy populates live interface and routing tables as a side effect of the import statement.
• A 293.2 KiB wheel against scapy's 2.63 MiB — 9.2× smaller.
• Regression-gated in CI, which — as far as we could establish by auditing ten comparable Python packet libraries' CI configurations (dpkt, scapy, pypacker, construct, pcapkit, dnspython, pyshark, nfstream, stackforge, PyTCP-net_proto; full citations in docs/CLAIMS.md §1.7) — none of them gate on one. Three of the ten (scapy, construct, stackforge) ship benchmark code that targets the library being compared but never runs in CI (construct disables it explicitly; stackforge's Criterion benches are never invoked). A fourth, PyTCP-net_proto, ships a benchmark too, but it exercises its RX daemon rather than the compared net_proto package, and isn't wired to CI either. A fifth, pcapkit, runs an engine benchmark weekly in CI, never on a pull request, and reports ratios without comparing them to an earlier run. None of the ten fails a build on a performance regression (re-audited 2026-11-04).
• Typed where the alternatives are not. mypy --strict over the whole of src/, enforced in CI. scapy ships py.typed but enables strict checking on 89 of its files, 2 of the 121 under scapy/layers/ — the dissectors most code touches stay Any. dpkt ships no py.typed at all, and no third-party stub package exists for it.
• The only MIT-licensed, strictly-typed, zero-dependency packet codec still under active maintenance. scapy is GPL-2.0; pypacker is GPLv2; the newer entrants stackforge and PyTCP-net_proto are both GPL-3.0. The other permissive option, dpkt (BSD), last released 2022-08-18 and last committed 2024-05-05, still targets Python 2.7 and 3.5–3.9, and remains marked Beta after twelve years.
• Runs where scapy cannot — including in the browser. Under a real Pyodide runtime in CI, netprotocols imports and decodes the full corpus cleanly. Scapy cannot even be attempted there: it is absent from Pyodide's package set, and from fcntl import ioctl is unconditional in scapy/arch/ — confirmed by that same CI run still missing the module, plus the source citation. dpkt and pypacker were both confirmed to import cleanly under the same missing modules, but via a separate CPython-side simulation, not inside the CI job.
• The only one of these libraries a match/case statement dissects out of the box. dpkt builds __slots__ from a metaclass and generates no __match_args__; scapy routes fields through __getattr__; construct returns dicts. None gives you a pattern to match against.

None of this makes scapy less than an extraordinary piece of software — it crafts, sends, sniffs and fuzzes across thousands of protocols, and this library does none of that. The comparison above is scoped to what both are: a codec that turns bytes into typed objects and back.

One mypy --strict run says more than the bullets above:

# scapy 2.8.0 — a field name that does not exist
p.ThisFieldDoesNotExist   → Any     (no error)

# dpkt 1.9.8 — the whole module
import dpkt.ethernet      → error: missing library stubs or py.typed

# netprotocols — a typo in a real field name
ip.proto                  → error: "IPv4" has no attribute
                              "proto"; maybe "protocol"?

decode_frame() walks the whole chain and hands back a Packet:

from netprotocols import TCP, decode_frame

packet = decode_frame(frame)
print(packet)                 # Packet(Ethernet(...), IPv4(...), TCP(...))
print(packet[1].src)          # '192.168.1.96' — position, unchanged
print(packet[TCP].flags_str)  # first TCP layer, or KeyError if none
print(packet.get(TCP))        # same lookup, None instead of raising
print(packet.consumed)        # bytes the headers occupied
print(packet.trailer)         # bytes past the declared lengths, b"" if none

It works because every header answers two questions: header_len (how many bytes it consumed) and next_protocol() (which class decodes what follows). Trailing bytes are fine. The 802.3, IPv4, IPv6 and UDP lengths end what the walk hands each layer, and the bytes past the tightest of them, such as Ethernet padding or a captured FCS, are packet.trailer; frame[packet.consumed : len(frame) - len(packet.trailer)] is whatever the chain did not decode before them, and frame == bytes(packet) + that + packet.trailer.

Start somewhere other than Ethernet when the buffer does — a tunnel payload, a packet quoted inside an ICMP error, a non-Ethernet link type:

decode_frame(buf, start=IPv4)

Malformed input raises exceptions rooted at a single base class:

from netprotocols import ProtocolError, TruncatedHeaderError, InvalidFieldError

try:
    packet = decode_frame(frame)
except TruncatedHeaderError:   # buffer shorter than the header claims
    ...
except InvalidFieldError:      # nonsense field values (IHL < 5, bad address)
    ...
except ProtocolError:          # catches every library error
    ...

Every decode and validation error carries structured context alongside its message — err.protocol names the class that raised, err.field names the attribute at fault where one field is at fault, and err.offset / err.frame_offset locate the problem in bytes (in the header's own buffer, and rebased to the whole frame when the error came through decode_frame) — so a fuzzer, conformance suite, or validation tool can act on where and what failed without parsing the message (capture-file and registry errors leave protocol unset):

try:
    packet = decode_frame(frame)
except ProtocolError as e:
    print(f"{e.protocol.__name__} at byte {e.frame_offset}: {e}")
    # IPv4 at byte 14: IPv4 IHL must be at least 5, got 0

A capture tool would usually rather keep the layers it got than lose frame 4,000,001 to an exception. lax=True reports instead of raising:

packet = decode_frame(frame, lax=True)
if packet.stopped_by is not None:
    log.warning("stopped after %d layers: %s", len(packet), packet.stopped_by)

Lax mode never invents a layer and never guesses — each header is decoded exactly as strictly as before; the walk just declines to throw away the part that worked. Chain depth is bounded (max_depth, default 32), so a crafted frame cannot make the walker grind.

One case where reaching for lax=True is the right default, not just a convenience: an ICMP error message's embedded packet. RFC 792 only guarantees the invoking IP header plus 8 bytes of what follows — never a full TCP/UDP header — so decoding it with the strict path raises on ordinary, correctly formed traffic. ICMPv4/ICMPv6 expose this pre-wired as embedded_chain:

icmp.embedded_chain  # decode_frame(icmp.embedded_packet, lax=True, start=IPv4)
                      # → Packet([IPv4(...)]), stopped_by=TruncatedHeaderError(...)

embedded_packet stays available for the raw bytes; reach for embedded_chain when you want them already decoded and are prepared to read stopped_by. Outside this one RFC-mandated case, a complete frame that fails to decode is still a bug to raise on — lax=True elsewhere is a capture tool's choice, not a default.

read_captures() takes a capture file opened in binary mode, or its bytes — not a path — and auto-detects classic pcap vs. pcapng from its magic number:

from netprotocols import decode_frame, read_captures

with open("traffic.pcap", "rb") as file:
    for timestamp, frame in read_captures(file):
        packet = decode_frame(frame, lax=True)
        ...

A file, an io.BytesIO, a pipe or any other object with a read(size) method is read forward from its current position, one record or block at a time and never seeked, so memory use follows the largest record or block, not the size of the capture; the 4-byte magic number is read on the call, the rest as you iterate. bytes, bytearray and memoryview (an mmap included) are copied once when iteration starts. A stream read from position 0 gives the frames and errors, offsets included, that its bytes give as a buffer; from a later position, offsets count from where reading started.

Each CapturedFrame is (timestamp, data) — timestamp normalized to nanoseconds since the Unix epoch regardless of the source format's own resolution (classic pcap's microseconds or nanoseconds; pcapng's per-interface if_tsresol). read_pcap()/read_pcapng() are the same thing for a caller who already knows the format and wants to skip detection. A malformed or truncated capture raises MalformedCaptureError, the same ProtocolError family every other exception in this library belongs to.

read_packets() detects the format the same way and yields CapturedPacket(timestamp, data, interface_id, interface_name): for a frame from a pcapng Enhanced Packet Block, the Interface ID it names and that interface's if_name (None when the interface has none); for a pcapng Simple Packet Block or a classic-pcap record, None for both.

Packet.flow_key() (or the free function, netprotocols.flow_key(), for a header pair that never went through decode_frame) returns a canonical, direction-independent key for a TCP, UDP or SCTP conversation — both directions of one flow produce the same key:

request = decode_frame(client_to_server_frame)
reply = decode_frame(server_to_client_frame)
assert request.flow_key() == reply.flow_key()

It returns None, not an error, when there is nothing to key on: no enclosing IP layer, no TCP/UDP/SCTP layer, or a transport layer without ports at all (ICMPv4/ICMPv6 — this library does not invent a port-slot convention for message types that have none).

decode() and decode_frame() stay per-frame. To put IP fragments back together, and TCP segments into each direction's byte stream, feed every decoded packet, with the frame it came from, to a FragmentReassembler and a StreamReassembler from netprotocols.reassembly, a module the package does not import on its own. A TCP segment rebuilt from fragments is fed to the stream reassembler with the frame that completed it:

from netprotocols import IPv4, IPv6, decode_frame, read_captures
from netprotocols.reassembly import (
    Datagram,
    FragmentReassembler,
    StreamReassembler,
)

fragments = FragmentReassembler()
streams = StreamReassembler()
for index, (ts, frame) in enumerate(read_captures(data)):
    packet = decode_frame(frame, lax=True)
    for event in fragments.feed(packet, frame, timestamp=ts, ref=index):
        handle((event,))
        if isinstance(event, Datagram):
            start = IPv4 if event.version == 4 else IPv6
            data = event.data
            whole = decode_frame(data, start=start, lax=True)
            handle(streams.feed(whole, data, timestamp=ts, ref=index))
    handle(streams.feed(packet, frame, timestamp=ts, ref=index))
handle(fragments.close() + streams.close())

Each Datagram carries the whole datagram with a rebuilt header, so the ordinary decoders and checksum helpers read it. Each StreamData carries bytes that just became contiguous in one direction of a TCP connection, at their stream offset, which is where the previous StreamData or Gap of that direction ended. Append them to that direction's buffer and decode HTTP, TLS or BGP messages from its start (see Decoding HTTP). A Gap means bytes are missing: the message pending in that direction's buffer is incomplete, so do not join the bytes before the gap to those after it; drop the buffer and resume decoding at a message boundary after the gap. Every event names its frames by the ref you passed: event.refs are every frame it came from, event.completing_ref the frame that completed it, and a message's completing frame is that of the run holding its last byte.

Overlapping IPv4 fragments are resolved by a per-target OverlapPolicy (first by default; last, bsd, linux, windows, solaris, discard, linux-discard), and overlapping TCP segments not yet delivered by first or last; any overlap whose bytes differ is reported as an Overlap event under every policy, and an overlapping IPv6 fragment discards its datagram (RFC 5722). Holes a capture missed but the receiver acknowledged become Gap events, an RST is reported at once and ends the stream at the closed timeout after it when no data follows it, at close(), or at once when a SYN with a new ISN follows, and every other rule a fragment or segment breaks is an Anomaly event, never an exception. What each reassembler holds is bounded, and measured on capture timestamps. Every feed() moves the capture clock, a frame with nothing to reassemble included, and returns the Expired events that causes; call advance(timestamp) while a live capture is idle:

HTTP.decode() reads one HTTP/1.1 message (RFC 9112) from the start of a buffer and leaves whatever follows it alone; header_len says where the message ended. The buffer has to be the connection's bytes, which you reassemble with netprotocols.reassembly (see above) or your own: a TCP segment is rarely a whole message, so HTTP is not in the port tables and decode_frame stops at TCP. Reading the messages pipelined on one side of a connection is a loop:

from netprotocols import HTTP, HTTPDisposition


def messages(stream, request_methods=()):
    """Each message on one side of a connection, in order. For the
    server's side, pass the methods of the requests it answered."""
    methods = iter(request_methods)
    while stream:
        msg = HTTP.decode(stream, request_method=next(methods, None))
        yield msg
        stream = stream[msg.header_len :]
        if msg.connection_disposition is not HTTPDisposition.CONTINUE:
            break  # closed, or no longer HTTP (an upgrade or a tunnel)

TruncatedHeaderError means the message is not all there yet; once the connection has closed, pass closed=True, which a response delimited by the close needs and which turns a short message into InvalidFieldError. A response's framing can depend on the request it answers, which the bytes do not say: a response to HEAD, or a 2xx to CONNECT, has no body whatever its Content-Length claims, so pass request_method.

>>> msg = HTTP.decode(response, request_method="HEAD")
>>> msg.status_code, msg.framing, msg.header("content-length"), msg.raw_body
(200, <HTTPFraming.NONE: 'none'>, '42', b'')

The message is held verbatim (bytes(msg) == msg.head + msg.raw_body), and anything implementations read differently is decoded the way RFC 9112 resolves it and reported, not rejected, so a smuggling attempt shows up instead of hiding behind an exception:

>>> msg = HTTP.decode(
...     b"POST / HTTP/1.1\r\nHost: a\r\nContent-Length: 4\r\n"
...     b"Transfer-Encoding: chunked\r\n\r\n0\r\n\r\n"
... )
>>> msg.framing, msg.connection_disposition
(<HTTPFraming.CHUNKED: 'chunked'>, <HTTPDisposition.CLOSE: 'close'>)
>>> [(a.kind.name, a.field, a.offset) for a in msg.anomalies]
[('CL_AND_TE', 'content-length', 26)]

Every decoded header works with match/case today, with no code written for it: a frozen dataclass auto-generates __match_args__, and every enum field is an IntEnum, so a class pattern can match a named value against the plain int the wire actually carries. See ARCHITECTURE.md for why both of those hold and how to keep them holding.

IPv4, TCP and DHCP are wide enough (11-15 fields) that their full auto-generated positional form is unusable, so those three additionally curate a short __match_args__ by hand — the fields someone matching by position actually reaches for:

match ip:
    case IPv4(src, dst, IPProtocol.TCP):
        print(f"TCP: {src} -> {dst}")

Keyword patterns (case IPv4(protocol=IPProtocol.TCP)) work on every field regardless, curated or not, and stay the documented default. HTTP's fields are raw bytes, so its __match_args__ names properties instead: case HTTP("GET", target) for a request, case HTTP(None, None, 404) for a response.

from netprotocols import IPv4, IPProtocol, TCP

match packet.layers:
    case [_, IPv4(protocol=IPProtocol.TCP) as ip, TCP(flags_str=f), *_] \
            if "SYN" in f and "ACK" not in f:
        print(f"connection attempt from {ip.src}")
    case [_, IPv4() as ip, TCP(), *_]:
        print(f"TCP from {ip.src}")
    case _:
        print("not a TCP-over-IPv4 frame")

The dispatch tables are public, so a protocol this library does not implement can join the walk without forking it:

from netprotocols import Protocol
from netprotocols.registry import register

@register("ethertype", 0x88B5)  # IEEE 802 Local Experimental
class Telemetry(Protocol):
    ...

The seven tables the walk reads are ethertype, llc.dsap, llc.snap, ip.proto, ip.proto.v6, udp.port and tcp.port, each named after the wire field it dispatches on. An eighth, sctp.ppid, maps an SCTP Payload Protocol Identifier to a decoder for the user data of an unfragmented DATA or I-DATA chunk; the walk ends at SCTP and never reads it, SCTPChunk.decode_user_data(registry) does, and it ships empty, since this library decodes no PPID's payload. To change decoding for one call only — DNS on a nonstandard port in one capture — say so per call instead of registering globally:

decode_frame(frame, decode_as={"udp.port": {6969: DNS}})

To stop a key from dispatching at all, map it to WITHHELD: it then dispatches to nothing, as a port nothing is registered on does, so the walk ends at UDP unless the other port names a class. None there raises TypeError. The same value withholds a key globally:

from netprotocols.registry import WITHHELD, register

decode_frame(frame, decode_as={"udp.port": {1812: WITHHELD}})
register("udp.port", 1812, WITHHELD, override=True)  # every walk

See ARCHITECTURE.md for how the tables fit together and how ip.proto.v6 inherits ip.proto.

Constructors take friendly values (string MAC/IP addresses, integer fields) and validate them; bytes() emits the exact on-wire form. Packet concatenates a stack of layers:

from netprotocols import ARP, Ethernet, Packet, random_mac

sha = random_mac()
frame = Packet(
    Ethernet(dst="ff:ff:ff:ff:ff:ff", src=sha, ethertype=0x0806),
    ARP(htype=1, ptype=0x0800, hlen=6, plen=4, oper=1,
        sha=sha, spa="192.168.1.96",
        tha="00:00:00:00:00:00", tpa="192.168.1.254"),
)
raw = bytes(frame)  # ready for a raw socket

Checksums are computed and verified on request — never silently: compute()/verify() in netprotocols.checksum (the internet checksum, VRRP's — the message alone in VRRPv2, behind the IP pseudo-header in VRRPv3, with VRRPv3 over IPv4 verified in either form — PIM's, CDP's with its odd final byte summed as Cisco does, and SCTP's CRC32c via crc32c(); OSPF's LSA checksums via lsa_checksum()/verify_lsa()), and Packet.with_checksums() to fill a whole stack before sending.

Every class exposes human-readable properties next to the raw fields: Ethernet.ethertype_name, IPv4.protocol_name, IPv4.flags_name, TCP.flags_str ("SYN ACK"), ARP.oper_name, ICMPv4.type_name, and hexadecimal renderings such as checksum_hex_str. Unknown values degrade gracefully ("0x88b5", "unknown (47)") instead of raising.

See ARCHITECTURE.md for a guided tour: how a header byte layout maps onto a dataclass, the decode contract, the next_protocol() chain, and a cookbook for adding a new protocol.

This library is the engine behind RootWire, a network traffic monitor built on it (formerly Packet-Sniffer).

The current roadmap, #170, closes the protocol gap against dpkt, scapy and pypacker in five tiers: transport and tunneling, routing, L2 discovery, AAA and infrastructure services, and TLS record framing with SNI. That issue tracks each tier's protocols and target version, so they are not restated here. The HTTP/1.1 codec (#214, #223, #226) shipped as 2.3.0 outside those tiers, and the first tier — IP-in-IP, VXLAN, ESP, AH and SCTP (#230, #231, #232, #233, #234) — as 2.4.0, and the second — VRRP, RIP, OSPF, PIM and BGP (#243, #245, #246, #247, #248) — as 2.5.0, and the third — MPLS, LLDP, LLC/SNAP, STP and CDP (#252, #253, #254, #255, #256) — as 2.6.0, and the fourth — TFTP, RADIUS, STUN, NTP and HSRP (#266, #265, #267, #269, #279) — as 2.7.0, and the fifth — TLS record framing with SNI (#284, #290) — as 2.8.0, which completes the roadmap's protocol tiers (see CHANGELOG.md).

The roadmap before it, the post-1.3.0 #107, is complete — five tiers plus a competitor CI audit (#124) and the comparative-claims embargo lift that closed it out:

Everything through 2.2.0 has landed on master. The since-landed decode-throughput fix (#147) and a CodeFactor tooling cleanup (#156) are now released as 2.2.1. 2.1.0's and 1.3.1/1.4.0's work shipped folded into 2.0.0 and 2.2.0 rather than as their own versions, but the roadmap's original "only at a major version bump" release policy wasn't actually held to: 2.0.0, 2.2.0, 2.2.1, 2.3.0, 2.4.0, 2.5.0, 2.6.0, 2.7.0, 2.8.0 and now 2.9.0 are all on PyPI, and the comparative claims above draw on the finished tree. The wave before that one — TCP and IPv4 option parsing, ICMP message bodies, NDP, IPv6 extension-header TLV options, the GRE checksum arm, a DNS-over-TCP corpus fixture and ipaddress accessors — shipped in 1.3.0; see CHANGELOG.md.

Development uses uv: uv sync, then the seven checks CI enforces: uv run ruff check, uv run ruff format --check, uv run flake8 src (docstrings, via pydoclint), uv run mypy, uv run pytest, python3 scripts/check_markers.py (no work markers) and uv run sphinx-build -W -n -b dummy docs <outdir> (docstring cross-references). The test suite runs across Python 3.12–3.14; ruff, flake8, mypy and Sphinx run on 3.12. The test suite is anchored by a 509-frame corpus of real captured traffic across 43 scenarios (tests/fixtures/MANIFEST.md, which says which layers a script built rather than the kernel) plus property-based fuzzing of the decode path. See CONTRIBUTING.md for the full workflow and ARCHITECTURE.md for the design and the add-a-protocol cookbook.

MIT