pydivert

library3.1.3pypypi✓ verified 24d ago

PyDivert is a powerful Python binding for the WinDivert driver, enabling user-mode applications to capture, modify, and drop network packets on Windows. It offers features like advanced filtering, on-the-fly packet manipulation, and re-injection into the network stack. Version 3.1.0 is the current release, and the library demonstrates an active release cadence, with major updates supporting modern Python features (like asyncio) and WinDivert 2.2+ capabilities, including bundled driver binaries.

http-networking auth-security

pip install pydivert

github ↗package ↗

INSTALL

IMPORT

SIG · PYDIVERT

pydivert

http-networkingpythonv3.1.3

Install

1.9s avg

Import

276ms

Disk

17MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.1.3 · 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.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.232s · 18.5MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.9s · import 0.210s · 19MB

17MB installed

● package 17MB

Code

Verified usage

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

WinDivert

✓ from pydivert import WinDivert

Main entry point for capturing and diverting packets.

Packet

✓ from pydivert import Packet

Represents a network packet for inspection and modification.

Layer

✓ from pydivert import Layer

Used to specify WinDivert capture layers (e.g., NETWORK, FLOW, SOCKET).

Flag

✓ from pydivert import Flag

Used to specify WinDivert handle flags (e.g., SNIFF, DROP).

This quickstart demonstrates how to capture outbound TCP packets destined for port 80 and then re-inject them back into the network stack. It highlights the basic usage of `pydivert.WinDivert` as a context manager and iterating over captured packets. Remember to run this with administrator privileges.

import pydivert import os # NOTE: This script requires administrator privileges to run. # On Windows, you might need to run your terminal/IDE as Administrator. # Example: Capture and re-inject all outbound TCP packets to port 80 (HTTP). # Packets captured are removed from the network stack; they must be re-injected to proceed. with pydivert.WinDivert("tcp.DstPort == 80 and outbound") as w: print("Capturing outbound TCP packets to port 80. Press Ctrl+C to stop.") try: for packet in w: print(f"Captured: {packet.src_addr}:{packet.src_port} -> {packet.dst_addr}:{packet.dst_port}") w.send(packet) # Re-inject the packet back into the stack except KeyboardInterrupt: print("\nStopped capturing.") except Exception as e: print(f"An error occurred: {e}")

Debug

Known issues

breakingPyDivert 3.0.0 introduced significant breaking changes, primarily affecting the `Packet` class constructor. It now accepts additional metadata fields (like `layer`, `event`, `flow`, `socket`, `reflect`), and the `interface` parameter became optional with a default of (0,0). Additionally, the `wd_addr` property now returns a full `WINDIVERT_ADDRESS` for all supported layers. Existing code that manually constructs `Packet` objects or relies on the previous `wd_addr` signature will require updates.

fix

Review the official PyDivert 3.x documentation and update `Packet` constructor calls and `wd_addr` usage to align with the new API. Ensure new metadata fields are handled if custom packet creation is performed.

affects: >=3.0.0

gotchaPyDivert requires administrator privileges to operate because it interacts directly with the Windows kernel-mode network driver. Running your application without these privileges will result in a runtime error or the application hanging when attempting to open a `WinDivert` handle.

fix

Always run Python scripts or the application that uses PyDivert with administrator privileges (e.g., 'Run as administrator' on Windows).

affects: All

gotchaWhen `pydivert.WinDivert` captures a packet using `recv()` (or by iterating over the `WinDivert` object), that packet is removed from the Windows network stack. If you intend for the packet to continue to its original destination or be injected elsewhere, you *must* explicitly call `w.send(packet)`. If `send()` is not called, the packet will be silently dropped.

fix

Always remember to call `w.send(packet)` after processing a packet if you want it to proceed through the network stack. Implement logic to explicitly drop packets if that is the desired behavior.

affects: All

gotchaPyDivert is a binding for WinDivert, which is a Windows-specific driver. Therefore, PyDivert itself is exclusively compatible with Microsoft Windows operating systems (64-bit editions, specifically Windows 11+ for full modern feature support). It will not function on Linux, macOS, or other non-Windows platforms.

fix

Ensure your development and deployment environment is a supported Windows operating system. Consider alternative packet manipulation libraries if cross-platform compatibility is a requirement (e.g., `scapy` on Linux/macOS).

affects: All

gotchaDue to its low-level interaction with the network stack, applications using PyDivert should adhere to strict security best practices. This includes employing the principle of least privilege (only running necessary components with admin rights) and rigorously validating all external inputs, especially those used in filter strings or packet modification logic, to prevent potential vulnerabilities or system instability.

fix

Implement robust input validation for all user-provided data, especially filter strings. Minimize the scope of administrator privileges for your application.

affects: All

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'pydivert'

The 'pydivert' module is not installed in the Python environment.

fix

Install the module using pip: 'pip install pydivert'.

ModuleNotFoundError: No module named 'pydivert.consts'

The 'pydivert' module is either not installed or not properly installed, leading to missing submodules.

fix

Uninstall and reinstall 'pydivert' to ensure all components are correctly installed: 'pip uninstall pydivert' followed by 'pip install pydivert'.

Exception: Could not import pydivert module. windivert requires https://pypi.org/project/pydivert

The 'pydivert' module is missing, which is required for the 'windivert' method in the application.

fix

Install the 'pydivert' module using pip: 'pip install pydivert'.

AttributeError: 'Packet' object has no attribute 'dst_port'

Attempting to access a non-existent attribute 'dst_port' on a 'Packet' object, possibly due to incorrect packet manipulation.

fix

Ensure that the 'Packet' object has the 'dst_port' attribute by verifying the packet's structure and the correctness of the code handling it.

ImportError: cannot import name 'WinDivert' from 'pydivert'

The 'WinDivert' class cannot be imported from the 'pydivert' module, possibly due to an outdated or incompatible version.

fix

Update 'pydivert' to the latest version compatible with your Python environment: 'pip install --upgrade pydivert'.

Upgrade

Version history

3.1.3latest on PyPI · released May 15, 2026

Audit

Dependencies

PythonrequiredRequires Python 3.10+ (64-bit) for full compatibility and features.

Windows OSrequiredPyDivert is a Windows-specific library, requiring Windows 11 (64-bit) or compatible Windows Server versions. It will not work on Linux or macOS.

Administrator PrivilegesrequiredInteracting with the WinDivert driver requires the application to run with administrator privileges.

WinDivert driverrequiredThe necessary 64-bit WinDivert DLL and driver are bundled with PyDivert, so no manual installation is typically required.

Agent activity

85 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/ffalcinelli/pydivert ↗

packagehttps://pypi.org/project/pydivert/ ↗