For technical and maintenance information, see the Official Documentation.
PyPCAPKit is an open-source Python library for parsing, constructing and analysing network packets and PCAP files, with DictDumper as its output dumper.
Compared with Scapy, DPKT and
PyShark, pcapkit reports more detail about each
packet through a more Pythonic interface. Where that depth is not needed, the same
interface drives those tools as third-party extraction engines.
Requires Python 3.8 or later. CI supports 3.11 to 3.15, and tests the end-of-life 3.8 to 3.10 without letting a failure block anything.
pip install pypcapkitOr from a clone, for unreleased changes and development:
git clone https://github.com/JarryShaw/PyPCAPKit.git
cd PyPCAPKit
pip install -e .The extraction engines and plug-ins are optional extras:
pip install pypcapkit[DPKT] # or Scapy, PyShark, PyPCAPFile, PyPCAP, PCAP_CT
pip install pypcapkit[crypto] # ESP payload decryption
pip install pypcapkit[cli] # command line interface
pip install pypcapkit[all] # core addons only: cli + crypto + NGAP (pycrate)Some engines need more than pip install -- a tshark binary, a C compiler, libpcap headers, or
an older interpreter -- and pypcap and pcap-ct must not be installed together. The
engine prerequisites
give each constraint and its reason. Asking for an engine that cannot run here warns
with the cause and falls back to pcapkit's own parser.
>>> import pcapkit
>>> extraction = pcapkit.extract('in.pcap', nofile=True)
>>> len(extraction.frame)
6
>>> frame = extraction.frame[0]
>>> str(frame.protochain)
'Ethernet:IPv6:ICMPv6'
>>> frame.info.time
datetime.datetime(2017, 11, 19, 15, 49, 5, 471719, tzinfo=datetime.timezone.utc)
>>> frame.payload.payload.src
IPv6Address('fe80::a6:87f9:2793:16ee')The output is from the committed examples/captures/in.pcap.
Reassembly, TCP flow tracing and the engine are keyword arguments to the same call:
>>> scapy = pcapkit.extract('in.pcap', nofile=True, engine='scapy')
>>> reasm = pcapkit.extract('in.pcap', nofile=True, reassembly=True, ipv6=True)
>>> flows = pcapkit.extract('in.pcap', nofile=True, trace=True, tcp=True)
>>> len(flows.trace.tcp)
2More examples, including the command line interface, are in How to ....
Pages of the official documentation worth knowing by name:
| Page | What is in it |
|---|---|
| API reference | Every module, protocol and constant |
| Module structure | What each subpackage is for |
| Engine comparison | Which engines exist, which Python versions they run on, what each needs installed, and measured speed per packet |
| Engine support | What each engine does not support, and how the gap is surfaced |
| Installation | Extras and the local development setup |
| Testing | Running the suite, and the sample captures it needs |
| How to ... | Worked examples, library and CLI |
| Extensions | Registering your own protocols, engines and dumpers |
The newest changelog entry is in CHANGELOG.md, which links to the full history; contribution guidelines are in CONTRIBUTING.md.