PyPCAPKit - Comprehensive Network Packet Analysis Library¶
PyPCAPKit is an open source Python library for PCAP file extraction, construction and analysis.
Important
The whole project requires Python 3.8 or later. CI supports 3.11 to 3.15, and still tests the end-of-life 3.8 to 3.10 without letting a failure block anything.
About¶
PyPCAPKit is an independent open source library, with
DictDumper as its formatted output dumper. Compared with
Scapy, DPKT and PyShark, it gives more detailed packet
information through a more Pythonic interface.
Deprecated since version 0.8.0: jspcapy, a command line tool for PCAP extraction built on pcapkit,
has been merged into PyPCAPKit as its CLI.
Module Structure¶
Subpackage |
Holds |
|---|---|
Interface ( |
the user-facing functions |
Foundation ( |
extraction, reassembly, flow tracing and the registries behind them |
Protocols ( |
every protocol family |
Utilities ( |
the cross-cutting services the library is built with |
CoreKit ( |
the core data structures, such as
|
ToolKit ( |
the per-engine adapters behind reassembly and flow tracing |
DumpKit ( |
the output dumpers added to those of |
Constants ( |
the constant enumerations, generated by |
Vendor ( |
the crawlers that regenerate |
Engine Comparison¶
Besides its own parser, pcapkit can extract through Scapy, DPKT,
PyShark, PyPCAP, pcap-ct and PyPCAPFile: every one of them but
PyShark is faster, and every one supports less. Engine Comparison compares their
support, Python versions, prerequisites and per-packet speed.
Installation¶
Note
The sources use 3.8 syntax and nothing converts them, since the bpc-*
backport tools are unmaintained (#2051), so requires-python is
>=3.8 and pip refuses an older interpreter. 3.8 to 3.10 are end-of-life
and best-effort, and individual engines stop earlier than the library
does; see Engine Prerequisites.
Install the current version from PyPI:
pip install pypcapkit
Or the latest version from the repository:
git clone https://github.com/JarryShaw/PyPCAPKit.git
cd PyPCAPKit
pip install -e .
# and to update at any time
git pull
For local development, make setup installs the Pipfile through
pipenv with the virtualenv and package caches inside the project directory,
and points lxml at Homebrew’s libxml2/libxslt where they are
installed. That avoids pipenv cache permission errors under
~/Library/Caches and lxml builds missing those headers:
make setup
To run pipenv directly, use the same cache layout and skip any stale,
user-local Pipfile.lock:
PIPENV_VENV_IN_PROJECT=1 \
PIPENV_CACHE_DIR=$PWD/.pipenv-cache \
PIP_CACHE_DIR=$PWD/.pip-cache \
pipenv install --skip-lock --dev
The optional engines and addons install as extras:
# for DPKT only
pip install pypcapkit[DPKT]
# for Scapy only
pip install pypcapkit[Scapy]
# for PyShark only
pip install pypcapkit[PyShark]
# for PyPCAPFile only
pip install pypcapkit[PyPCAPFile]
# for PyPCAP only -- builds from source, see below
pip install pypcapkit[PyPCAP]
# for pcap-ct only -- pure Python, works on 3.12+; never alongside PyPCAP
pip install pypcapkit[PCAP_CT]
# for ESP payload decryption
pip install pypcapkit[crypto]
# every core addon -- CLI display, ESP decryption and NGAP decoding;
# no engine above is included
pip install pypcapkit[all]
# or explicitly
pip install pypcapkit emoji cryptography pycrate
Important
all leaves out pypcap and pcap-ct on purpose. pypcap compiles a
C extension, which would demand a compiler and the libpcap development
files from everyone installing pypcapkit[all]; everything else in all
installs from a wheel. pcap-ct needs no compiler, but it and its
libpcap dependency are published only as pre-releases (1.3.0b3 and
1.11.0b29), and all should not install a beta nobody asked for. Install
either through its own extra, as above.
Changed in version 1.5.0: all installs the core addons only: emoji, cryptography and
pycrate. The engines and vendor-crawler dependencies it carried in 1.4
– dpkt, scapy, pyshark, requests and beautifulsoup4 –
moved to the dev extra, alongside pypcapfile (#910).
Warning
Install only one of pypcap and pcap-ct. Both own the top-level
pcap module, and pip installs both without complaint. pcap-ct then
wins the import and shadows pypcap’s extension module, so
engine='pypcap' stops working – measured on Python 3.10. pcapkit
warns with an EngineWarning naming both
distributions and the winner, but cannot undo it.
Some engines need more than a pip install – a tshark binary, a C
compiler and the libpcap headers, or an older interpreter.
Engine Prerequisites gives each constraint and its reason.
The CLI needs the cli extra:
pip install pypcapkit[cli]
# or explicitly
pip install pypcapkit emoji