Install & Compatibility
Where this runs
tested against v0.12.11 · 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
py 3.10
✕ build_error
1/2 runs
py 3.11
✕ build_error
1/2 runs
py 3.12
✕ build_error
✓ 4.15s
py 3.13
✕ build_error
✓ 4.1s
py 3.9
✕ build_error
1/2 runs
12MB installed
● package 12MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
executable_path
✓ from mitmproxy_linux import executable_path
✗ from mitmproxy_linux import executable_path
Path
✓ from mitmproxy_linux import Path
✗ from mitmproxy_linux import Path
mitmproxy-linux facilitates the 'local capture mode' for the main mitmproxy application on Linux. To use it, you install `mitmproxy` (which includes or depends on `mitmproxy-linux`) and then run the `mitmproxy` or `mitmweb` command-line tools with the `--mode local` or `--mode local:<process_name>` flag. Root privileges (`sudo`) are required to load the eBPF program for local interception.
# To enable mitmproxy's local capture mode using mitmproxy-linux:
# Ensure mitmproxy is installed (pip install mitmproxy)
# Run mitmproxy with the local mode flag:
sudo mitmproxy --mode local
# To capture traffic from a specific application (e.g., curl):
sudo mitmproxy --mode local:curl
# Or, for the web interface:
sudo mitmweb --mode local
Debug
Known issues
breakingLocal capture mode (which relies on mitmproxy-linux) requires root privileges (`sudo`) to load the eBPF program, as it interacts with the Linux kernel at a low level.fixAlways run `mitmproxy --mode local` or `mitmweb --mode local` commands with `sudo`.
affects: All versions supporting local capture mode on Linux.
gotchamitmproxy-linux relies on eBPF instrumentation, which requires a reasonably recent Linux kernel. Official support is for Linux 6.8 and above (e.g., Ubuntu 22.04). Older kernels may not function correctly.fixEnsure your Linux distribution is running a kernel version 6.8 or newer for reliable operation of local capture mode.
affects: All versions supporting local capture mode on Linux.
gotchaThe local capture mode on Linux, facilitated by mitmproxy-linux, currently only supports capturing outbound (egress) connections. For inbound connections, other proxy modes like reverse proxy mode are recommended.fixBe aware of the egress-only limitation for local capture mode. Consider using `reverse proxy mode` for intercepting inbound connections.
affects: All versions supporting local capture mode on Linux.
gotchaThe `mitmproxy-linux` package itself does not provide a direct user-facing Python API for scripting. Its role is infrastructural. User scripting is done via the main `mitmproxy` package's addon API (e.g., `from mitmproxy import http`).fixTo script mitmproxy functionality, install and use the `mitmproxy` library, not `mitmproxy-linux` directly. Refer to the mitmproxy documentation on addons.
affects: All versions.
Upgrade
Version history
0.12.11latest on PyPI · released Jul 20, 2026
Audit
Dependencies
mitmproxyrequiredmitmproxy-linux is a specialized component used by the main mitmproxy application for local traffic redirection on Linux. Its functionality is exposed through the mitmproxy CLI and API.
mitmproxy_rsrequiredThis package is part of the mitmproxy_rs Rust project, which provides the underlying implementation for WireGuard and local redirect modes across platforms.