PyShark

0.6 · active · verified Sun Apr 12

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.

Warnings

breaking PyShark 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.
gotcha PyShark 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.
deprecated The 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.
gotcha When 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}')`.
gotcha On 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.
gotcha There 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.

Install

pip install pyshark Install PyShark

Imports

LiveCapture
```
from pyshark import LiveCapture
```
FileCapture
```
from pyshark import FileCapture
```

Quickstart

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

view raw JSON →