pytcpdump

A minimal tcpdump-like packet capture tool built with Python and libpcap.

Advantages

• Lean dependency model: directly calls libpcap via ctypes, thus having no bundled binary dependencies.
• Familiar workflow: supports tcpdump-style BPF expressions (for example, tcp port 443).
• Flexible packaging: supports shiv (.pyz), pex (.pex), and nuitka (native executable).

Requirements

• Python >=3.10
• On Windows, install Npcap/WinPcap first (provides wpcap.dll)

Common Commands

# List interfaces
uv run python main.py -D

# Capture packets (example)
uv run python main.py "tcp and port 80"

# Capture on a specific interface and stop after 20 packets
uv run python main.py -i "<interface>" -c 20 udp

# Write packets to a pcap file
uv run python main.py -i "<interface>" -q -w capture.pcap "tcp port 443"

Packaging

Shiv (.pyz)

uv run --with shiv python build_shiv.py
uv run --with shiv python build_shiv.py --output-file dist/custom/pytcpdump.pyz

Pex (.pex)

uv run --with pex python build_pex.py
uv run --with pex python build_pex.py --output-file dist/custom/pytcpdump.pex

Notes:

• build_pex.py installs dependencies into a temporary bundle first, then invokes pex.
• This avoids common Windows path issues during direct pex resolution.

Nuitka (Native Executable)

uv run --with nuitka python build_nuitka.py
uv run --with nuitka python build_nuitka.py --mode standalone
uv run --with nuitka python build_nuitka.py --output-dir dist/custom

Notes:

• Default output directory: dist/nuitka
• Uses Nuitka import inference by default (no hardcoded include flags)

CLI Options

• -i, --interface: capture interface name
• -D, --list-interfaces: list interfaces and exit
• -c, --count: stop after receiving COUNT packets (0 means unlimited)
• -s, --snapshot-length: snapshot length in bytes
• -p, --no-promiscuous: disable promiscuous mode
• -w, --write: write captured packets to a .pcap file
• -q, --quiet: do not print packet summaries
• -t, --timeout-ms: read timeout in milliseconds
• expression: BPF filter expression (tcpdump style)