mitmproxy-linux (Local Traffic Redirector for mitmproxy)

0.12.9 · active · verified Sat Apr 11

mitmproxy-linux is a component package within the broader mitmproxy ecosystem, currently at version 0.12.9, which was last released on January 30, 2026. It specifically provides the Linux traffic redirection capabilities for mitmproxy's 'local capture mode', leveraging eBPF technology to intercept traffic from specific applications without system-wide proxy settings. This package is not a standalone proxy but rather a backend dependency used by the main mitmproxy tools (mitmproxy, mitmweb, mitmdump) to enable advanced local interception features on Linux. The mitmproxy project itself has a regular release cadence, with the main library currently at version 12.2.1 as of November 24, 2025.

Warnings

breaking Local 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.
Fix: Always run `mitmproxy --mode local` or `mitmweb --mode local` commands with `sudo`.
gotcha mitmproxy-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.
Fix: Ensure your Linux distribution is running a kernel version 6.8 or newer for reliable operation of local capture mode.
gotcha The 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.
Fix: Be aware of the egress-only limitation for local capture mode. Consider using `reverse proxy mode` for intercepting inbound connections.
gotcha The `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`).
Fix: To script mitmproxy functionality, install and use the `mitmproxy` library, not `mitmproxy-linux` directly. Refer to the mitmproxy documentation on addons.

Install

pip install mitmproxy-linux Install via pip
pip install mitmproxy Install main mitmproxy (includes local mode support)

Imports

mitmproxy-linux

This package is primarily a backend dependency; direct Python imports for user-facing functionality are not typically performed by end-users. Its features are exposed via the mitmproxy CLI, e.g., 'mitmproxy --mode local'.

Users typically interact with mitmproxy-linux functionality through the main 'mitmproxy' command-line tools or its Python API for addons, not by importing 'mitmproxy-linux' directly.

http
```
from mitmproxy import http
```
This import is for writing mitmproxy addons, typically used with the main 'mitmproxy' package, not 'mitmproxy-linux' directly. mitmproxy-linux enables underlying functionality for these addons to work in local mode.

Quickstart

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

view raw JSON →