This file is a plain-text extract of the documentation at
https://github.com/stamparm/pcapy-ng/blob/master/README.md
(the full documentation, with examples, is in README.md).


What is Pcapy-NG?
=================

Pcapy-NG is a Python extension module that lets Python programs use the libpcap
packet-capture library. It is a maintained replacement for Pcapy, which is no
longer maintained and stopped working on Python 3.10. The classic Pcapy API
(open_live, open_offline, loop, next, setfilter, dump_open, ...) is unchanged,
so existing Pcapy code keeps working.

On top of that it provides an optional set of capture primitives for programs
where per-packet Python work is the bottleneck:

 * loop_filtered()  - classify packets in C, invoke the callback only for the
                      classes you admit (flow heads, large IPv4 address-set
                      matches, or a built-in security profile).
 * loop_to_buffer() - same classification, but writes admitted packets into a
                      buffer you provide, with the GIL released.
 * filtered_stats() - live per-class counters, pollable from another thread.
 * next_batch()     - read up to N packets in a single call.
 * set_fanout()     - join a live handle to a Linux PACKET_FANOUT group so
                      several handles can share one interface's traffic.


Setup
=====

Install from PyPI:

    pip install pcapy-ng

Releases from 2.0.1 on provide Linux and macOS wheels for CPython 3.9-3.14 with
libpcap vendored in. There are no Windows wheels; on Windows, and on any other
platform or interpreter, pip builds from the sdist.

Building from source requires:

 * A Python interpreter. 2.7 and 3.x are supported.
 * A C++ compiler.
 * Libpcap and its headers (libpcap-dev / libpcap-devel). On Windows, the
   Npcap SDK, with WPDPACK_BASE pointing at it.

To build and install a checkout:

    pip install .


Licensing
=========

This software is provided under the Apache Software License.
See the accompanying LICENSE file for more information.


Contact Us
==========

Whether you want to report a bug, send a patch or give some suggestions on this
package, drop a few lines at contact@sekuripy.hr or open an issue at
https://github.com/stamparm/pcapy-ng/issues.
