Registry / http-networking / pyshark

pyshark

JSON →
library0.6pypypi✓ verified 24d ago

PyShark is a Python wrapper for TShark, the command-line network protocol analyzer that comes with Wireshark. It allows for Pythonic packet parsing and analysis by leveraging Wireshark's powerful dissection engine. The library is currently at version 0.6 and sees active development with several minor and patch releases per year, addressing compatibility and adding features.

pip install pyshark
INSTALL
IMPORT
SIG · PYSHARK
P
pyshark
http-networkingpythonv0.6
Install
2.3s avg
Import
274ms
Disk
29MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.6 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.280s · 31.2MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 2.3s · import 0.268s · 32MB
29MB installed
● package 29MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

LiveCapture
from pyshark import LiveCapture
FileCapture
from pyshark import FileCapture

This quickstart demonstrates how to perform a live packet capture using `pyshark.LiveCapture`. It sniffs 5 packets on a specified network interface (defaulting to 'eth0' or an environment variable) and prints basic information about each packet. It also includes error handling for the common `TShark not found` issue and ensures the capture process is properly closed. Remember to replace 'eth0' with your actual network interface name or set the `PYSHARK_INTERFACE` environment variable.

import pyshark import os # Ensure TShark is installed and in your system's PATH. # For Windows, you might need to specify the interface like r'\Device\NPF_{YOUR-GUID}' # For macOS, 'en0' or 'en1' are common. # For Linux, 'eth0' or 'wlan0' are common. interface_name = os.environ.get('PYSHARK_INTERFACE', 'eth0') try: # Create a LiveCapture object to sniff on the specified interface # Use display_filter for Wireshark-style filtering, e.g., 'http or dns' capture = pyshark.LiveCapture(interface=interface_name) print(f"Capturing 5 packets on {interface_name}...") for packet in capture.sniff_continuously(packet_count=5): # Access packet layers and fields protocol = packet.highest_layer src = packet.ip.src if 'IP' in packet else 'N/A' dst = packet.ip.dst if 'IP' in packet else 'N/A' print(f"Packet: {packet.number} | Time: {packet.sniff_time} | Protocol: {protocol} | Source: {src} -> Dest: {dst}") # Example: print DNS query name if available if 'DNS' in packet and hasattr(packet.dns, 'qry_name'): print(f" DNS Query: {packet.dns.qry_name}") except FileNotFoundError: print("Error: TShark not found. Please ensure Wireshark/TShark is installed and in your system's PATH.") except Exception as e: print(f"An error occurred during capture: {e}") finally: if 'capture' in locals() and capture: capture.close() # Important: ensure the capture process is closed to prevent resource leaks
tshark --version
Debug
Known issues
breakingPyShark dropped official support for Python 3.5 and 3.6 starting with version 0.6.
fix
Upgrade to Python 3.7 or newer. Python 3.7+ is officially supported.
affects: >=0.6
gotchaPyShark fundamentally relies on `tshark` (the command-line tool for Wireshark) being installed and accessible in your system's PATH. Without `tshark`, PyShark cannot function and will raise a `FileNotFoundError` or similar exception.
fix
Install Wireshark (which includes TShark) for your operating system and ensure `tshark` is added to your system's PATH environment variable. Verify installation by running `tshark --version` in your terminal.
affects: All
deprecatedThe older JSON parsing mode is 'likely to be eventually deprecated' in favor of the newer, faster, and easier-to-use EK parsing mode introduced in v0.5.
fix
Migrate your parsing logic to use the EK (Elasticsearch-compatible JSON) mode for improved performance and future compatibility. Enable it by passing `use_ek=True` to your capture object.
affects: >=0.5
gotchaWhen capturing on Windows, network interface names are typically in the format `\Device\NPF_{GUID}` rather than common names like 'Wi-Fi' or 'Ethernet'. Using the wrong format will result in capture failure.
fix
Identify the correct NPF interface name for your adapter. You can often find this by running `pyshark.LiveCapture.interfaces()` or checking TShark's output directly. Example: `capture = pyshark.LiveCapture(interface=r'\Device\NPF_{YOUR-ADAPTER-GUID}')`.
affects: All
gotchaOn macOS, `pyshark` might require `libxml` and Xcode command-line developer tools to be installed due to underlying dependencies.
fix
Run `xcode-select --install` and `pip install libxml` (or `brew install libxml2` if using Homebrew) to resolve potential compilation issues.
affects: All
gotchaThere have been reports of parsing errors or incomplete data when using EK mode (`use_ek=True`) in combination with `include_raw=True`, particularly where fields like flags might appear empty.
fix
If experiencing issues with missing or malformed fields in EK mode, try disabling `include_raw=True` if raw packet data is not strictly required for that specific operation. Check GitHub issues for potential workarounds or updates.
affects: >=0.5
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'email.utils'; 'email' is not a package
This error occurs when there's a naming conflict due to a user-created file named 'email.py' in the working directory, which shadows Python's standard 'email' module.
fix
Rename or remove the 'email.py' file in your working directory to avoid the naming conflict.
RuntimeError: maximum recursion depth exceeded while calling a Python object
This error arises when attempting to pickle or pass PyShark packet objects through a multiprocessing queue, due to the library's internal handling of attributes.
fix
Avoid pickling PyShark packet objects or passing them through multiprocessing queues; instead, extract necessary data from packets before such operations.
AttributeError: 'Packet' object has no attribute 'tcp.analysis_ack_rtt'
This error occurs when attempting to access the 'tcp.analysis_ack_rtt' attribute on packets that do not contain this field.
fix
Before accessing 'tcp.analysis_ack_rtt', check if the attribute exists using 'hasattr(packet.tcp, 'analysis_ack_rtt')' to prevent the error.
RuntimeError: Event loop is closed
This error happens when the event loop is closed before all asynchronous tasks are completed, often due to improper handling of asynchronous operations in PyShark.
fix
Ensure that all asynchronous tasks are awaited properly and that the event loop remains open until all tasks are completed; consider using 'asyncio.run()' to manage the event loop.
FileNotFoundError: [Errno 2] No such file or directory: 'tshark'
This error occurs when TShark is not installed or not accessible in the system's PATH, which is required for PyShark to function.
fix
Install Wireshark (which includes TShark) and ensure that the TShark executable is added to your system's PATH environment variable.
Upgrade
Version history
0.6latest on PyPI · released Apr 26, 2023
Audit
Dependencies
tsharkrequiredPyShark is a wrapper around TShark, the command-line utility for Wireshark. TShark must be installed and accessible in your system's PATH for PyShark to function. It is typically installed as part of the Wireshark suite.
appdirsrequiredRuntime dependency for directory management.
termcolorrequiredRuntime dependency for colored terminal output. Replaced 'py' dependency in v0.6.
packagingrequiredRuntime dependency for version parsing.
lxmlrequiredRuntime dependency for XML parsing, as PyShark utilizes TShark's XML export capabilities.
Agent activity
24 hits · last 30 days
node
20
OpenAI (training)
2
Resources
pyshark — pip install pyshark · libregistry