This release is a pre-release and may not be stable for production use.
PyPCAPKit - Comprehensive Network Packet Analysis Library
For any technical and/or maintenance information, please kindly refer to the Official Documentation.
The PyPCAPKit project is an open source Python program focus on network packet parsing and analysis, which works as a comprehensive PCAP file extraction, construction and analysis library.
The whole project supports Python 3.6 or later.
About
PyPCAPKit is a comprehensive Python-native network packet analysis library, with DictDumper as its formatted output dumper.
Unlike popular PCAP file extractors, such as Scapy, DPKT, PyShark, and etc, pcapkit is designed to be much more comprehensive, which means it is able to provide more detailed information about the packet, as well as a more Pythonic interface for users to interact with.
Module Structure
In pcapkit, all files can be described as following eight parts.
Interface (pcapkit.interface)
User interface for the pcapkit library, which standardises and simplifies the usage of this library.
Foundation (pcapkit.foundation)
Synthesises file I/O and protocol analysis, coordinates information exchange in all network layers, as well as provides the foundamental functions for pcapkit.
Protocols (pcapkit.protocols)
Collection of all protocol family, with detailed implementation and methods.
Utilities (pcapkit.utilities)
Auxiliary functions and tools for pcapkit.
CoreKit (pcapkit.corekit)
Core utilities for pcapkit implementation, mainly for internal data structure and processing.
ToolKit (pcapkit.toolkit)
Auxiliary tools for pcapkit to support the multiple extraction engines with a unified interface.
DumpKit (pcapkit.dumpkit)
File output formatters for pcapkit.
Constants (pcapkit.const)
Constant enumerations used in pcapkit for protocol family extraction and representation.
Engine Comparison
Due to the general overhead of pcapkit, its extraction procedure takes around 0.2 milliseconds per packet, which is already impressive but not enough comparing to other popular extraction engines available on the market, given the fact that pcapkit is a comprehensive packet processing module.
Additionally, pcapkit introduced alternative extraction engines to accelerate this procedure. By now pcapkit supports Scapy, DPKT, PyShark, PyPCAP and PyPCAPFile, selected through engine='scapy', 'dpkt', 'pyshark', 'pypcap' and 'pypcapfile' respectively; engine='default' (also spelled 'pcapkit') is pcapkit’s own parser and the only one with no third-party requirement.
Speed is not free. Every third-party engine supports less than the default one, and the two newest support markedly less:
PyPCAP performs no protocol dissection at all, so it offers neither reassembly nor flow tracing, and reads PCAP savefiles from disk only.
PyPCAPFile has no IPv6 decoder, so IPv6 reassembly is unavailable; IPv4 and TCP reassembly still work, and it too is PCAP-only.
PyShark performs no reassembly.
Each gap is announced with a warning or an exception rather than silently returning nothing. The engine support documentation tabulates them.
Test Environment
Operating System |
macOS Ventura 13.4.1 |
Chip |
Apple M2 Pro |
Memory |
16 GB |
Test Results
Measured with examples/legacy_smoke/test_time.py over 1,000 timed extractions of examples/captures/in.pcap per engine, on the environment above.
Engine |
Performance (ms per packet) |
|---|---|
dpkt |
0.010390_056723 |
scapy |
0.091690_233567 |
pcapkit |
0.200390_390390 |
pyshark |
24.682185_018351 |
pypcap |
not measured [1] |
pypcapfile |
not measured [2] |
Both figures will be filled in once the two engines can be timed on the same host, capture and iteration count as the existing rows.
Installation
Note – pcapkit supports Python versions since 3.6.
Simply run the following to install the current version from PyPI:
pip install pypcapkitOr install the latest version from the gi repository:
git clone https://github.com/JarryShaw/PyPCAPKit.git
cd pypcapkit
pip install -e .
# and to update at any time
git pullFor local development with pipenv, the repository already includes a Pipfile and Makefile targets that keep both the virtualenv and the package caches inside the project directory:
make setupThis resolves two common local setup issues on macOS/Homebrew installations: pipenv cache permission errors under ~/Library/Caches and lxml builds failing to locate Homebrew’s libxml2/libxslt headers.
If you prefer to run pipenv directly, use the same local 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 --devAnd since pcapkit supports various extraction engines, and extensive plug-in functions, you may want to install the optional ones:
# 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 -- see the note below, this one builds from source
pip install pypcapkit[PyPCAP]
# for ESP payload decryption
pip install pypcapkit[crypto]
# and to install the optional packages -- note this excludes PyPCAP
pip install pypcapkit[all]
# or to do this explicitly
pip install pypcapkit dpkt scapy pyshark pypcapfile
**Important** -- The ``all`` extra deliberately does **not** include
``pypcap``. Everything
else in ``all`` is a pure-Python wheel, whereas ``pypcap`` compiles a C
extension; pulling it into ``all`` would demand a working compiler and the
`libpcap`_ development files from everyone installing ``pypcapkit[all]``.
Install it explicitly with ``pip install pypcapkit[PyPCAP]``.Engine prerequisites
Three of the engines need something beyond a pip install:
- pyshark
Drives Wireshark’s tshark binary, which must be on PATH. Install Wireshark (or just tshark) from your platform’s package manager.
- pypcap
Ships no wheels – only an sdist – so pip compiles it, and the build needs both libpcap’s headers (pcap.h) and its shared or static library:
# Debian/Ubuntu sudo apt-get install libpcap-dev # RHEL/Fedora/Amazon Linux sudo dnf install libpcap-devel # macOS brew install libpcapTwo caveats, both upstream problems rather than pcapkit ones:
pypcap 1.3.0 ships a pre-generated pcap.c produced by Cython 0.29.x, which does not compile against the Python 3.12+ C API. Having libpcap installed is therefore necessary but not sufficient: on 3.12 or newer the build fails whatever else is present. Use Python 3.11 or older for this engine, or regenerate pcap.c with Cython 3 yourself.
Its setup.py does not consult CFLAGS/LDFLAGS or pkg-config. It searches a fixed list of prefixes – /usr, sys.prefix, /opt/libpcap*, ../libpcap*, ../wpdpack* and the macOS SDKs – so a libpcap installed anywhere else, notably Homebrew’s keg-only prefix on Apple Silicon (/opt/homebrew/opt/libpcap), is not found even though it is installed. Installing into sys.prefix, or into /opt/libpcap, is what that search will pick up.
- pypcapfile
Version 0.12.0 imports the imp module, which was removed in Python 3.12, so pcapfile.savefile – the module needed to read a capture – cannot be imported at all on 3.12 or newer. Upstream master has fixed this but no release carries the fix yet, so this engine also requires Python 3.11 or older until 0.12.1 is published.
Note – pcapkit itself, and its default, dpkt and scapy engines, work fine on current Python versions. Only the three engines above carry these extra constraints, and asking for an engine whose package is unavailable emits a warning and falls back to pcapkit’s own parser rather than failing outright.
For CLI usage, you will need to install the optional packages:
pip install pypcapkit[cli]
# or explicitly...
pip install pypcapkit emojiTesting
The unit tests need nothing beyond the package itself and the sample captures tracked in the repository:
make testThe runtime, regression and integration tests additionally read sample captures that are not tracked (see .gitignore); examples/generators/make_samples.py reconstructs them into examples/captures/, and make test-all regenerates them before running the whole suite:
make samples # write examples/captures/*.pcap and *.pcapng
make test-all # regenerate the fixtures, then run every testThe same fixtures back the demonstration scripts in examples/legacy_smoke/, which read them as ../captures/….
Continuous integration runs the make test selection, since the fixtures are not in the repository. tshark is only required to exercise the PyShark engine, and is not needed by the test suite.
1 maintainer
Release files for pypcapkit 1.5.0a1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| pypcapkit-1.5.0a1.tar.gz | 1.1 MB | Details |
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| pypcapkit-1.5.0a1-pp311-none-any.whl | PyPy 3.11 | none | any | Details |
| pypcapkit-1.5.0a1-pp310-none-any.whl | PyPy 3.10 | none | any | Details |
| pypcapkit-1.5.0a1-cp314-none-any.whl | CPython 3.14 | none | any | Details |
| pypcapkit-1.5.0a1-cp313-none-any.whl | CPython 3.13 | none | any | Details |
| pypcapkit-1.5.0a1-cp312-none-any.whl | CPython 3.12 | none | any | Details |
| pypcapkit-1.5.0a1-cp311-none-any.whl | CPython 3.11 | none | any | Details |
| pypcapkit-1.5.0a1-cp310-none-any.whl | CPython 3.10 | none | any | Details |
Total release size: 8.8 MB
Release files / pypcapkit-1.5.0a1.tar.gz
| Download URL | pypcapkit-1.5.0a1.tar.gz |
|---|---|
| Size | 1.1 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5d2d63dc8d6f4636dade778eede087903570d84d23fef86ea572e81e9e7feeba
|
|
BLAKE2b-256 checksum How to use checksums |
8e1b9932c0be4df44cf04c4f9e6c48d3d35445aab1b722633358d7a0ccdc4251
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / pypcapkit-1.5.0a1-pp311-none-any.whl
| Download URL | pypcapkit-1.5.0a1-pp311-none-any.whl |
|---|---|
| Size | 1.1 MB |
| Tags | PyPy 3.11 |
|
SHA-256 checksum How to use checksums |
942b3d06516b53003a99bcf774bdfa8dea83542fe2ade0786ae6fab0ed55df95
|
|
BLAKE2b-256 checksum How to use checksums |
2126f7a97aacafc1b97d98292c19456eeae5b010e04f0e7feb07bf056753f8d7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / pypcapkit-1.5.0a1-pp310-none-any.whl
| Download URL | pypcapkit-1.5.0a1-pp310-none-any.whl |
|---|---|
| Size | 1.1 MB |
| Tags | PyPy 3.10 |
|
SHA-256 checksum How to use checksums |
5fde84727a98f9e5b07e5e52d59c048b7f05904ff28c2de93a46feccccb611c7
|
|
BLAKE2b-256 checksum How to use checksums |
8d2105ab232380e277f2119eeedf48d2eaedaebd997ab929e8a1b9a30bdd19e9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / pypcapkit-1.5.0a1-cp314-none-any.whl
| Download URL | pypcapkit-1.5.0a1-cp314-none-any.whl |
|---|---|
| Size | 1.1 MB |
| Tags | CPython 3.14 |
|
SHA-256 checksum How to use checksums |
8059905c384d4fdf2e298588e3b4b86320f34496860c4b8388f483040806185a
|
|
BLAKE2b-256 checksum How to use checksums |
1786d5a52853261d9565e03859e766f8bf9f6c5d0066b45baf5c4923783b65a9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / pypcapkit-1.5.0a1-cp313-none-any.whl
| Download URL | pypcapkit-1.5.0a1-cp313-none-any.whl |
|---|---|
| Size | 1.1 MB |
| Tags | CPython 3.13 |
|
SHA-256 checksum How to use checksums |
905144b1c69fc0aba9707858b6c73b4931f15c2fbcbe353e87ac79a3b068876b
|
|
BLAKE2b-256 checksum How to use checksums |
9972106162d75874348b1905e30a7519961fd6ca4c022ccada136f42af9ca88b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / pypcapkit-1.5.0a1-cp312-none-any.whl
| Download URL | pypcapkit-1.5.0a1-cp312-none-any.whl |
|---|---|
| Size | 1.1 MB |
| Tags | CPython 3.12 |
|
SHA-256 checksum How to use checksums |
428e04e346c22a7f0a7d9f4ecb5859978292a17e7160799a114cdcce7921362f
|
|
BLAKE2b-256 checksum How to use checksums |
d02d58341c0560594c218924ca214bbfe1018db57c8d684beffada540e4a575e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / pypcapkit-1.5.0a1-cp311-none-any.whl
| Download URL | pypcapkit-1.5.0a1-cp311-none-any.whl |
|---|---|
| Size | 1.1 MB |
| Tags | CPython 3.11 |
|
SHA-256 checksum How to use checksums |
329aafea64c7b7be60bca43ebc34363855d9bf21a91ee364c7b6fe56b2a473f1
|
|
BLAKE2b-256 checksum How to use checksums |
51fa07410ced0b133b35c54289aecea7cdeea4c5f8f26cae0243aa065efdec5b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / pypcapkit-1.5.0a1-cp310-none-any.whl
| Download URL | pypcapkit-1.5.0a1-cp310-none-any.whl |
|---|---|
| Size | 1.1 MB |
| Tags | CPython 3.10 |
|
SHA-256 checksum How to use checksums |
9974f500948d74f47b643cb0a638a108b65667c53ea8e116b3ecc6db930aeacb
|
|
BLAKE2b-256 checksum How to use checksums |
9be1872f2f0c052735293d18d121c5c6bd665ed075d34145e1f577c7976ebb8e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
