Install & Compatibility
Where this runs
tested against v0.1.23 · 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
muslpy 3.10–3.95 runs
build_error
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.020s · 22MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Server
✓ from mitmproxy_wireguard import Server
Direct programmatic interaction with mitmproxy_wireguard is less common; users typically engage via the mitmproxy CLI (`mitmproxy --mode wireguard`). The Server class represents a running WireGuard server instance.
TcpStream
✓ from mitmproxy_wireguard import TcpStream
Provides APIs identical to Python's `asyncio.StreamReader` and `asyncio.StreamWriter` for established TCP connections. Generally used internally by mitmproxy.
start_server
✓ from mitmproxy_wireguard import start_server
A coroutine to initialize, start, and return a Server instance. Most users will use `mitmproxy --mode wireguard` instead of directly calling this.
The primary way to use mitmproxy-wireguard's functionality is through the `mitmproxy` CLI tools (mitmproxy, mitmweb, or mitmdump) using the `--mode wireguard` option. This starts a WireGuard VPN server. Clients then connect using a standard WireGuard application, importing the configuration (often via a QR code or a file at `~/.mitmproxy/wireguard.conf`) provided by mitmproxy. After connecting, the mitmproxy CA certificate must be installed on the client device by navigating to `http://mitm.it`.
# To run mitmproxy in WireGuard mode, install mitmproxy first.
# pip install mitmproxy
import subprocess
import time
import os
print("Starting mitmweb in WireGuard mode. This will open a browser window.")
print("Connect your WireGuard client to the displayed configuration (QR code or file in ~/.mitmproxy/wireguard.conf).")
print("Then, from the connected device, navigate to http://mitm.it to install the CA certificate.")
# Ensure mitmproxy is in the PATH or provide full path
mitmproxy_cmd = ["mitmweb", "--mode", "wireguard", "--web-host", "127.0.0.1", "--web-port", os.environ.get('MITMWEB_PORT', '8081')]
# You might need to adjust this if mitmweb doesn't start in a way that allows direct subprocess control
# For typical usage, users would run this command directly in a terminal.
# This example is illustrative of the command, not a robust programmatic launch.
try:
# Start mitmweb in a non-blocking way if possible, or instruct user to run it.
# For simplicity in a quickstart, we'll just print the command.
print(f"\nRun this command in your terminal: {' '.join(mitmproxy_cmd)}\n")
# In a real scenario, you'd use subprocess.Popen for background execution
# p = subprocess.Popen(mitmproxy_cmd)
# p.wait() # Or handle it asynchronously
except FileNotFoundError:
print("Error: 'mitmweb' command not found. Please ensure mitmproxy is installed and in your PATH.")
except Exception as e:
print(f"An error occurred: {e}")
# Example of what a user would do after starting mitmweb:
# 1. Configure WireGuard client using the QR code or ~/.mitmproxy/wireguard.conf
# 2. On the client, browse to http://mitm.it to install the CA certificate.
# 3. All traffic from the WireGuard client will now be intercepted by mitmproxy.
mitmweb --version
Debug
Known issues
breakingThe standalone `mitmproxy-wireguard` project is no longer maintained as a separate entity; its functionality has been subsumed into `mitmproxy_rs` and is now an integrated part of the main `mitmproxy` project. While the functionality persists, direct development on this specific PyPI package has ceased.fixEnsure you are using a recent version of the `mitmproxy` project (mitmproxy 9+), which includes and maintains this WireGuard mode functionality. Refer to the mitmproxy documentation for the latest usage.
affects: All versions of mitmproxy-wireguard as a standalone project.
gotchaIPv6 traffic support in WireGuard mode is limited. Generated client configurations may not list IPv6 addresses by default. While the server supports receiving IPv6 packets, proxying them is incomplete.fixTo enable incomplete IPv6 support, manually add `::/0` or other desired IPv6 ranges to the `AllowedIPs` setting in the WireGuard client configuration.
affects: All current versions (0.1.x) and integrated mitmproxy versions (9+).
gotchaIt is not possible to proxy all traffic of the host machine where `mitmproxy` itself is running in WireGuard mode. This limitation prevents an infinite loop where outgoing WireGuard packets are sent over the WireGuard tunnel they originate from.fixUse WireGuard mode for external devices or specific applications on the same device where the application does not route its own traffic through the VPN. For local host traffic, consider other mitmproxy modes like 'local' or 'transparent' (though transparent mode setup is more complex).
affects: All current versions (0.1.x) and integrated mitmproxy versions (9+).
gotchaUsing `--allow-hosts` or `--ignore-hosts` options with `mitmproxy` in WireGuard mode can sometimes lead to issues where all traffic breaks, often related to DNS resolution.fixIf experiencing issues, try removing `--allow-hosts` or `--ignore-hosts` arguments. If host filtering is critical, carefully test specific IP/hostname patterns and monitor `mitmproxy`'s event log for DNS-related errors. Consider implementing filtering logic within a mitmproxy addon if CLI options prove problematic.
affects: mitmproxy versions 9+ (where WireGuard mode is integrated).
gotchaChrome browsers do not trust user-added Certificate Authorities for QUIC (HTTP/3) by default, even after installing the mitmproxy CA certificate. This causes Chrome to fall back to HTTP/2.fixTo enable HTTP/3 interception in Chrome, you can either provide a publicly trusted certificate to mitmproxy, start Chrome with a specific command-line switch (`--ignore-certificate-errors` or similar, which is not recommended for general browsing), or accept that Chrome will fall back to HTTP/2. Firefox does not have this limitation.
affects: mitmproxy versions 11+ (with HTTP/3 support).
gotchaiOS clients may fail to trust the mitmproxy CA certificate in WireGuard mode, even after installing it as a profile and explicitly enabling 'Full Trust for Root Certificates' in iOS settings. This results in certificate errors for HTTPS sites.fixThis can be a persistent issue on iOS. Double-check all steps: ensuring the WireGuard VPN is active, the CA certificate is installed, and 'Full Trust' is enabled. If the problem persists, it may indicate a deeper iOS-specific trust store interaction that can be challenging to debug or resolve consistently. Consider alternative proxy modes or devices if this remains a blocker.
affects: mitmproxy versions 9+ when used with iOS clients.
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'mitmproxy_wireguard'
The standalone `mitmproxy_wireguard` Python package is not installed, or the Python environment where it's being imported lacks access to it. While `mitmproxy` (version 11.x and newer) integrates WireGuard functionality, this specific error occurs if a user or script attempts to directly import the separate `mitmproxy-wireguard` library.
fixIf you intend to use `mitmproxy`'s integrated WireGuard mode, you typically do not need to `import mitmproxy_wireguard` in your Python code; you simply run `mitmproxy --mode wireguard`. If you have a specific reason to use the standalone library directly in a script, install it via `pip install mitmproxy-wireguard`.
Address already in use (when starting mitmproxy in WireGuard mode)
The default UDP port for the WireGuard server (usually 51820) or a custom port specified for `mitmproxy` is already occupied by another application or process on your system.
fixChange the listening port for `mitmproxy`'s WireGuard server by specifying it in the command, for example: `mitmproxy --mode wireguard@51821`. Alternatively, identify and stop the process currently using the conflicting port.
mitmproxy wireguard traffic not intercepted
Although the WireGuard client may show as connected, traffic is not correctly being routed through `mitmproxy` or is not being processed by it. Common reasons include incorrect `AllowedIPs` or `Endpoint` settings in the client's WireGuard configuration, local firewall rules blocking traffic, or a missing/untrusted `mitmproxy` CA certificate on the client device preventing HTTPS interception.
fixVerify that the WireGuard client configuration has `AllowedIPs = 0.0.0.0/0` (for IPv4 traffic) and that the `Endpoint` points to the correct IP address and UDP port of your `mitmproxy` server. Check `mitmproxy`'s event log for `clientconnect` messages. Ensure the `mitmproxy` CA certificate is installed and trusted on the client device by navigating to `http://mitm.it` in a browser *after* establishing the WireGuard VPN connection.
mitmproxy wireguard dns not working
Clients connected via `mitmproxy`'s WireGuard mode are unable to resolve domain names, leading to websites not loading or network applications failing. This indicates an issue with DNS resolution within the WireGuard tunnel.
fixConfirm that the `DNS` setting in your WireGuard client configuration is correctly pointing to the IP address of `mitmproxy`'s internal DNS server (typically `10.0.0.53` or similar, as provided in the generated WireGuard configuration). If you've configured custom DNS settings in `mitmproxy`, double-check their correctness.
Upgrade
Version history
0.1.23latest on PyPI · released Apr 4, 2023
Audit
Dependencies
mitmproxyrequiredThis library's functionality is primarily exposed and used as a mode within mitmproxy.
pythonrequiredRequires Python >=3.7. Note that mitmproxy itself requires Python >=3.9.
rustoptionalRequired for building from source (Rust 1.58.0+).
maturinoptionalRequired for building from source (maturin 0.13.x).