CLI tool
KimiNewt/pyshark avatar
KimiNewt/pyshark

pyshark: parsing packets with tshark instead of reimplementing Wireshark

Python wrapper for tshark, allowing python packet parsing using wireshark dissectors

2,502 stars449 forksPythonMIT

At a glance

What is it?
pyshark is a Python wrapper around the tshark command line tool. It ships no dissectors of its own, which is both why it works and where it stops.
Who is it for?
Adopt pyshark when the dissector coverage of an installed Wireshark is what you need and a subprocess per capture is acceptable. Do not adopt it for high-rate inline processing, for environments where you cannot install tshark, or when you need packet bytes rather than decoded fields.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Activity is slowing. The repository last received commits 8 months ago.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 22, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • KimiNewt/pyshark2,502 ★ · +6
Star history
Repository2026-09-292026-11-22
KimiNewt/pyshark2.5k2.5k

6 Stars in the last 54 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

What pyshark solves that a pure Python parser does not

Writing a packet parser means writing dissectors: the code that turns bytes on the wire into named fields for Ethernet, IP, TCP, TLS, and everything above them. Wireshark already has that code, and tshark exposes it on the command line. pyshark's README states the design plainly: it "doesn't actually parse any packets, it simply uses tshark's (wireshark command-line utility) ability to export XMLs to use its parsing." The Python layer starts tshark, reads its output, and hands back objects whose attributes match the field names Wireshark uses.

The audience is narrow and specific. If you already reach for tshark in a shell to inspect a capture, pyshark lets you keep that workflow inside a Python script, with the same dissectors and the same filter syntax. If you need to process a pcap in a loop, correlate fields across packets, or feed decoded values into another Python library, the wrapper removes the parsing step you would otherwise write yourself. The README also notes it is tested on Windows and Linux, and that it supports all modern versions of tshark, with the caveat that "certain features may be unavailable on older versions."

The README carries a maintenance note worth reading before you commit: the author writes that he has "a hard time finding time to maintain and enhance the package at the moment" and asks for contributors. The repository is not archived and the last push was on 2026-03-22, so work continues, but the latest release listed is v0.6 from 2023-04-26. Treat the release cadence and the contributor request as the honest signal about pace.

The tshark subprocess is the architecture

Every capture class in pyshark maps to a way of invoking tshark. FileCapture points tshark at a file. LiveCapture points it at an interface. LiveRingCapture adds tshark's ring buffer options. RemoteCapture talks to a host running rpcapd. In each case the Python object is a thin controller over a subprocess, and the packet objects you get back are built from tshark's decoded output.

That design determines the failure modes. The cost of decoding is paid by tshark, not by Python, and the boundary between them is text or XML that has to be parsed. It also means the parameter list is really a list of tshark flags passed through. FileCapture accepts display_filter, only_summaries, disable_protocol, decryption_key, encryption_type and tshark_path. LiveCapture accepts interface, bpf_filter, display_filter, output_file and the same decryption options. The two filters are not interchangeable: bpf_filter is applied before reading, display_filter is a Wireshark display filter applied on the capture.

only_summaries deserves attention because the README describes it as "much faster but includes very little information." That is the trade you make when you only need packet-level metadata rather than dissected fields. If your script reads deep protocol attributes, only_summaries is the wrong switch, and the speed advantage disappears the moment you turn it off.

Installing pyshark and reading a first capture file

pyshark installs from PyPI. Python 3.7 or newer is required; a separate unsupported Python 2 version exists as pyshark-legacy. The wrapper does not bundle tshark, so a working tshark installation has to be present on the machine, either on PATH or pointed at with tshark_path.

bash
pip install pyshark

On macOS the README warns that libxml may be needed and gives the commands for that case. With the package installed, the smallest useful program opens a capture file and reads packets from it. The README's own example uses a .cap file and prints the first packet, which shows the layer structure tshark produced.

python
import pyshark

cap = pyshark.FileCapture('/tmp/mycapture.cap')
print(cap[0])

The printed object shows a length and then each layer in turn, with fields such as Destination, Source, Protocol and Time to live under the IP layer. Those names come from the dissector, not from pyshark, which is why an unfamiliar protocol still gives you readable output. For a live interface the pattern changes to LiveCapture and an explicit interface name.

python
import pyshark

capture = pyshark.LiveCapture(interface='eth0')
capture.sniff(timeout=50)
for packet in capture.sniff_continuously(packet_count=5):
    print('Just arrived:', packet)

sniff() fills the capture for a fixed timeout; sniff_continuously() yields packets as they arrive and stops after packet_count. If interface is omitted, the README says the first available interface is used, which is convenient for a quick test and a bad idea in anything that runs unattended.

Memory, rate and the limits of wrapping a subprocess

The keep_packets parameter on FileCapture controls whether packets are retained after next() returns. The README frames this as memory conservation when reading large captures, and it is the first thing to set when a file is bigger than your available RAM. A capture object that holds every packet it has ever seen will grow until it does not fit.

The deeper limitation is throughput. Because each capture is backed by a tshark process and the decoded output crosses a process boundary, pyshark is a poor fit for line-rate traffic or for pipelines that must not drop packets. tshark itself can keep up with more than the Python side can consume, and the wrapper adds parsing on top. If your requirement is capture at high rates with minimal loss, the right tool is tshark writing to disk or a capture library that works in-process, with pyshark used afterwards on the resulting file.

A second boundary is environmental. The library needs a tshark binary with the dissectors you rely on. On a stripped-down container or a locked-down host where you cannot install Wireshark, pyshark has nothing to call. The README's note that certain features may be unavailable on older tshark versions is the same constraint from the other direction: the wrapper can only expose what the installed tshark supports.

pyshark vs Scapy: decode versus craft

The comparison people reach for is Scapy, and the difference is architectural rather than a matter of taste. Scapy builds and dissects packets in Python. It can construct packets, send them, and manipulate them layer by layer, and its parsing is its own code. pyshark parses nothing; it delegates to tshark and returns what tshark decoded.

That makes Scapy the better choice when you need to forge traffic or work with packets as mutable objects. It makes pyshark the better choice when you want Wireshark's dissector coverage without maintaining dissectors, and when the display filter syntax you already know from Wireshark is the interface you want. The cost of pyshark's approach is the subprocess, the dependency on an external binary, and the fact that you receive decoded fields rather than raw bytes to reinterpret.

pyshark is also not a replacement for tshark itself. If a shell pipeline with tshark -r and a display filter answers your question, adding Python in the middle buys you nothing. pyshark earns its place when the decoded output has to feed Python logic: aggregation, comparison against other data, or storage.

Licence, upgrades and what the project does not promise

pyshark is MIT licensed, which places few restrictions on commercial use and modification. The licence file sits at the top level as LICENSE.txt. The practical implication is that you can vendor or fork it, which matters given the README's explicit request for contributors. Note that the MIT licence covers pyshark, not Wireshark or tshark, which are separate projects with their own terms.

Upgrade cost is low on the Python side: the package installs from PyPI and the release history shows long gaps between versions, with v0.6 in April 2023 following v0.5.3 in July 2022. The moving part is tshark. Because pyshark passes your parameters through to the installed tshark, a tshark upgrade can change what your filters accept even when the pyshark version is unchanged. requirements.txt lists lxml, py, pytest, appdirs, packaging and termcolor, and is marked as development requirements only, so those are not what a normal install pulls in.

The README does not document rollback behaviour, version pinning for tshark, or a compatibility matrix between pyshark releases and tshark releases. If your deployment depends on a specific tshark build, that pinning is on you.

Editorial conclusion

Adopt pyshark when the dissector coverage of an installed Wireshark is what you need and a subprocess per capture is acceptable. Do not adopt it for high-rate inline processing, for environments where you cannot install tshark, or when you need packet bytes rather than decoded fields. Verify first that tshark is on PATH or that tshark_path resolves, that your Python is 3.7 or newer, and that the display_filter you intend to use is accepted by your installed tshark version.

Frequently asked questions

What is pyshark used for?

It parses packet captures and live traffic from Python by calling tshark and using Wireshark's dissectors, so you get decoded protocol fields inside a Python script instead of writing your own parser.

What are the differences between pyshark and tshark?

pyshark does not parse packets itself. It starts tshark, reads the decoded output, and exposes the fields as Python objects, so tshark does the decoding and pyshark is the Python interface to it.

Can I use Wireshark with Python?

pyshark is one way to do it: it wraps tshark, the Wireshark command line utility, and uses the dissectors you have installed. The README states that this is exactly the point of the package.

How do I install pyshark?

Run pip install pyshark. Python 3.7 or newer is supported, and tshark must be installed on the machine, either on PATH or set through tshark_path.

Does pyshark work on Windows?

The README states the package is tested on Windows and Linux. On Windows, RemoteCapture notes that the remote interface is the true interface name rather than the device display name.

Official sources

  1. Issues
  2. KimiNewt/pyshark on GitHub
  3. License: MIT
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/kiminewt-pyshark.svg)](https://hysenlabs.com/projects/kiminewt-pyshark)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/kiminewt-pyshark.svg)](https://hysenlabs.com/projects/kiminewt-pyshark)

Was this useful?