mitmproxy Tutorial (2026): Inspect HTTPS, Write Addons and Chain an Upstream Proxy

Developer guide · Last reviewed 17 November 2026 · 21 min read

mitmproxy is a free, open-source intercepting proxy that lets you read, filter and rewrite the HTTP and HTTPS traffic your own tools send and receive. This mitmproxy tutorial shows how to install it, trust its CA certificate safely, find the JSON API behind a web page, write Python addons that save responses, and chain mitmproxy to an upstream proxy so traffic is inspected on your machine but exits through a residential IP. Everything here was checked against mitmproxy 12.3.1 (released 25 October 2026), its source and the official docs.

The short version

Install mitmproxy (it needs Python 3.12 or newer if you install from PyPI), run mitmweb --listen-host 127.0.0.1, point your client at http://127.0.0.1:8080 and trust the CA in ~/.mitmproxy/mitmproxy-ca-cert.pem. Use mitmdump -s addon.py to automate with Python hooks such as request(flow) and response(flow). To send the traffic out through another proxy, add --mode upstream:http://v2.proxyempire.io:5000 --upstream-auth USERNAME:PASSWORD. Only intercept traffic you own or are authorized to inspect.

Version note. Commands, option names and defaults below are from mitmproxy 12.3.1, read from the wheel published on PyPI and the docs at docs.mitmproxy.org. Option names change occasionally between major versions; run mitmdump --options to see the list for the version you have.

Key takeaways

  • mitmproxy ships three front ends over one core: a terminal UI (mitmproxy), a browser UI (mitmweb, port 8081) and a scriptable CLI (mitmdump).
  • The proxy listens on port 8080 on all interfaces by default. Bind it to 127.0.0.1, especially when it holds upstream credentials.
  • HTTPS inspection works only for clients that trust your mitmproxy CA. Its private key in ~/.mitmproxy/mitmproxy-ca.pem must stay private.
  • Addons are plain Python classes with event methods; response(flow) plus flow.response.json() is enough to save API data.
  • Apps with certificate pinning won’t accept mitmproxy’s certificates without modification. Leave those hosts alone or exclude them with ignore_hosts.

What mitmproxy, mitmweb and mitmdump Are

One proxy core, three ways to drive it

The project README describes mitmproxy as “an interactive, SSL/TLS-capable intercepting proxy” for HTTP/1, HTTP/2 and WebSockets. It sits between a client and the servers it talks to. For plain HTTP it simply relays and records. For HTTPS it terminates TLS on its side, generates a certificate for each host on the fly, signs it with its own certificate authority (CA), and opens a separate TLS connection to the real server. A client that trusts that CA sees a valid connection; mitmproxy sees the decrypted requests and responses in between.

The same package installs three commands:

mitmproxyAn interactive terminal UI. Browse flows, filter, intercept and edit requests by keyboard. Good over SSH.
mitmwebThe same features in a browser UI, served on 127.0.0.1:8081 by default and protected by a random token unless you set web_password.
mitmdumpThe non-interactive version. The README calls it “tcpdump for HTTP”. It prints flows, writes them to files and runs addons, which makes it the one for scripts and servers.

All three share options, flow filters and the addon API. mitmproxy is MIT-licensed and developed on GitHub.

Installing mitmproxy

Binaries first, PyPI when you need addon dependencies

The installation page recommends:

  • macOS: Homebrew, brew install --cask mitmproxy, or the standalone binaries from mitmproxy.org.
  • Linux: the standalone binaries. The docs warn that distribution packages “often lag behind the current mitmproxy release”.
  • Windows: the installer from mitmproxy.org, or the Microsoft Store version, which updates itself. Under WSL, follow the Linux instructions.
  • From PyPI: the docs recommend uv tool install mitmproxy. If your addons import extra packages, add them with uv tool install --with <package> mitmproxy. Plain pip in a virtual environment also works, but the project says it can’t support every installer.
  • Docker: official images are published as mitmproxy/mitmproxy on Docker Hub.

The PyPI package for 12.3.1 declares Requires-Python >=3.12 and lists 3.12 through 3.15 as supported. On an older interpreter, such as the Python 3.9 that ships with some macOS and Linux systems, pip install mitmproxy will either fail or resolve to an old release. The standalone binaries bundle their own Python, so they sidestep the problem; you only need a 3.12+ environment if your addons import third-party packages.

Example 1 — install and check the version (Bash)
# macOS
brew install --cask mitmproxy

# Any OS with uv installed
uv tool install mitmproxy

# Docker: persist ~/.mitmproxy so the CA survives restarts
docker run --rm -it -v ~/.mitmproxy:/home/mitmproxy/.mitmproxy \
  -p 127.0.0.1:8080:8080 mitmproxy/mitmproxy mitmdump

mitmdump --version

The Docker Hub page notes that without the -v mount, a new root CA is generated on every container start, which means re-trusting it each time.

The mitmproxy CA Certificate and mitm.it

The step that makes HTTPS visible, and the one to handle carefully

On first start, mitmproxy creates a CA in its config directory, ~/.mitmproxy. The certificates page lists the files:

FileContainsUse it for
mitmproxy-ca.pemCertificate and private keyNothing outside mitmproxy. Keep it secret.
mitmproxy-ca-cert.pemCertificate only (PEM)curl, Python, Linux and macOS trust stores
mitmproxy-ca-cert.p12Certificate only (PKCS12)Windows
mitmproxy-ca-cert.cerSame as the .pem, different extensionSome Android devices

The quickest way to install it on a device is the built-in onboarding app. Configure the device or browser to use the proxy, then open http://mitm.it. mitmproxy answers that hostname itself and offers the certificate with per-platform instructions.

For scripts, the docs give one-line installs: sudo security add-trusted-cert -d -p ssl -p basic -k /Library/Keychains/System.keychain ~/.mitmproxy/mitmproxy-ca-cert.pem on macOS and certutil -addstore root mitmproxy-ca-cert.cer on Windows. Linux steps differ by distribution, and the docs link to guides for each.

Security implications

Trusting a CA means trusting anyone who holds its private key to impersonate any website to that machine. mitmproxy generates a unique CA per installation, so another mitmproxy user can’t intercept your traffic with theirs. Your own key is the risk:

  • Don’t copy mitmproxy-ca.pem anywhere it doesn’t need to be: shared drives, container images, Git repositories.
  • Prefer per-client trust (a --cacert flag or a verify= path) over system-wide trust when you only need to inspect one tool.
  • Remove the CA from system stores when the debugging job ends, and use a separate browser profile for intercepted browsing.
  • Leave upstream verification on. The ssl_insecure option (-k) disables mitmproxy’s own checks of server certificates; the option’s help text warns that mitmproxy itself then becomes vulnerable to interception.

mitmproxy Proxy Modes

How traffic gets into mitmproxy

A mode decides how clients reach mitmproxy. The syntax is --mode name[:data][@[host:]port], and --mode can be repeated to run several servers at once. These are the modes in 12.3.1, from the modes documentation and mode_specs.py:

ModeSyntaxWhat it does
regular--mode regular (default)Explicit HTTP(S) proxy on port 8080. Clients must be configured to use it.
upstream--mode upstream:http://host:portLike regular, but every request is forwarded to another HTTP or HTTPS proxy.
reverse--mode reverse:https://hostActs as the server itself and forwards everything to one fixed target. Useful in front of an API you run.
socks5--mode socks5A SOCKS5 proxy, default port 1080.
local--mode local[:process]Captures traffic on this machine, optionally only from named processes or PIDs. Windows, Linux and macOS.
wireguard--mode wireguard[:keyfile]A userspace WireGuard server on UDP 51820. Good for phones and devices that ignore proxy settings.
transparent--mode transparentIntercepts redirected traffic at the network layer. Linux and macOS; the docs now suggest WireGuard or local mode instead.
tun--mode tun[:name]Creates a TUN interface. Linux only, needs root or CAP_NET_ADMIN.
dns--mode dnsA DNS server on port 53 that resolves via the OS.

For scraper work, regular mode (your code sets a proxy), local mode (capture a program that won’t take a proxy setting) and upstream mode (send everything on to another proxy) cover most needs. If the forward/reverse distinction is fuzzy, see our forward proxy vs reverse proxy explainer.

One security default to know: regular mode listens on all interfaces (listen_host is empty), and the block_global option only blocks clients with public IP addresses. Machines on your local network can still connect. Add --listen-host 127.0.0.1 unless you deliberately need LAN access, or require a login with --proxyauth username:pass.

Pointing curl, requests and Playwright at mitmproxy

Proxy setting plus CA trust, per client

Start the web UI first: mitmweb --listen-host 127.0.0.1. It opens http://127.0.0.1:8081 in your browser and listens for proxy traffic on port 8080. Then each client needs two things: the proxy address and trust in the CA.

Example 2 — curl through mitmproxy, trusting only its CA (Bash)
curl --proxy http://127.0.0.1:8080 \
  --cacert ~/.mitmproxy/mitmproxy-ca-cert.pem \
  https://api.ipify.org?format=json

--cacert replaces curl’s CA bundle for that command only, so nothing system-wide changes. Our curl proxy guide covers the other proxy flags and environment variables.

Example 3 — Python requests through mitmproxy (Python)
import os

import requests

MITM = "http://127.0.0.1:8080"
CA_BUNDLE = os.path.expanduser("~/.mitmproxy/mitmproxy-ca-cert.pem")

session = requests.Session()
session.proxies = {"http": MITM, "https": MITM}
session.verify = CA_BUNDLE  # trust mitmproxy's CA for this session only

r = session.get("https://api.ipify.org?format=json", timeout=30)
print(r.status_code, r.json())

requests does not expand ~, hence os.path.expanduser. Don’t “fix” certificate errors with verify=False: it hides real problems once the proxy is removed.

Example 4 — Playwright Chromium through mitmproxy (Python)
from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(proxy={"server": "http://127.0.0.1:8080"})
    # Only for a local debugging proxy: accept mitmproxy's certificates
    # without adding its CA to the system trust store.
    context = browser.new_context(ignore_https_errors=True)
    page = context.new_page()
    page.goto("https://www.example.com/")
    print(page.title())
    browser.close()

ignore_https_errors is a new_context() parameter in Playwright for Python. It is acceptable here because the only TLS the browser sees is mitmproxy’s, and mitmproxy still verifies the real servers. Never carry it over to production code that connects directly. For the wider picture of proxies in requests, httpx, Scrapy and Playwright, see Python web scraping with residential proxies.

Finding the JSON API Behind a Page

Let the browser show you where the data comes from

Many pages render from JSON that the browser fetches after the HTML loads. Requesting that JSON directly is usually lighter and more stable than parsing markup. mitmproxy makes the endpoint easy to spot:

  1. Load the page through mitmweb using Example 4 or a browser profile set to the proxy.
  2. Filter the flow list. mitmweb’s search box takes flow filter expressions: ~ts json matches responses with a JSON content type, ~d example.com limits to a domain, and &, | and ! combine them. !~a hides CSS, JavaScript, images and fonts.
  3. Read the request. Note the method, path, query parameters, any POST body and headers the server may require, such as an Accept header, a CSRF token or an API key the page itself embeds.
  4. Reproduce it. mitmweb has a Copy as cURL action for a selected flow (the export formats in 12.3.1 are curl, httpie, raw, raw_request and raw_response). Run that command, then strip headers one by one to see which ones matter.
  5. Check pagination. Scroll or click “next” and compare the two requests; the difference is usually a page number, offset or cursor.

Our JSON web scraping guide covers parsing the results, nested structures and embedded JSON such as __NEXT_DATA__ once you have found the endpoint. The same method debugs your own scraper: compare what your code sends with what the browser sent.

Writing a mitmproxy Addon in Python

A class with event methods, loaded with -s

An addon is any object with methods named after mitmproxy events. A script exposes its addons in a module-level addons list and is loaded with -s script.py in all three tools. Per the addons overview, scripts are watched for changes and reloaded on save, so you can edit while traffic flows.

The events you will use most:

HookFires whenTypical use
load(loader)The addon is loadedRegister custom options with loader.add_option()
configure(updated)Options change, including at start-upValidate options, open files
request(flow)The full request has been readModify, block or answer requests
response(flow)The full response has been readInspect or save responses
error(flow)A connection or protocol error occurredLog failures; per the source, each flow gets either response or error
done()mitmproxy shuts downFlush and print summaries

flow is an mitmproxy.http.HTTPFlow. flow.request has method, pretty_url, pretty_host, path, headers and query; flow.response has status_code, headers, text and json(). Options are read through mitmproxy.ctx.options. For logging, use Python’s standard logging module: ctx.log is deprecated and emits a warning in 12.x.

An addon that saves JSON responses

This addon writes every JSON response (optionally only those matching a flow filter) to a directory, one file per response, with the URL, method and status alongside the parsed body. Request headers are deliberately not saved, because they often contain cookies and tokens.

Example 5 — save_json.py: store JSON API responses on disk (Python)
"""
save_json.py: a mitmproxy addon that saves JSON responses to disk.

Run it with any of the three tools, for example:
    mitmdump -s save_json.py --set json_dir=captured --set json_filter="~d example.com"
"""
import json
import logging
import re
import time
from pathlib import Path
from typing import Optional

from mitmproxy import ctx, exceptions, flowfilter, http

logger = logging.getLogger(__name__)
SAFE = re.compile(r"[^A-Za-z0-9]+")


class SaveJSON:
    def __init__(self) -> None:
        self.filter: Optional[flowfilter.TFilter] = None
        self.saved = 0

    def load(self, loader) -> None:
        loader.add_option(
            "json_dir", str, "captured_json",
            "Directory for saved JSON responses.",
        )
        loader.add_option(
            "json_filter", Optional[str], None,
            "Only save flows matching this filter, e.g. '~d api.example.com'.",
        )

    def configure(self, updated) -> None:
        if "json_filter" in updated:
            expr = ctx.options.json_filter
            try:
                self.filter = flowfilter.parse(expr) if expr else None
            except ValueError as e:
                raise exceptions.OptionsError(f"Invalid json_filter: {e}")
        if "json_dir" in updated:
            Path(ctx.options.json_dir).mkdir(parents=True, exist_ok=True)

    def response(self, flow: http.HTTPFlow) -> None:
        if flow.response is None:
            return
        ctype = flow.response.headers.get("content-type", "").lower()
        if "json" not in ctype:
            return
        if self.filter is not None and not flowfilter.match(self.filter, flow):
            return
        try:
            body = flow.response.json()
        except (ValueError, TypeError):
            logger.warning("Skipping non-JSON body from %s", flow.request.pretty_url)
            return

        self.saved += 1
        host = SAFE.sub("_", flow.request.pretty_host)
        path = SAFE.sub("_", flow.request.path.split("?")[0]).strip("_")[:60] or "root"
        name = f"{int(time.time() * 1000)}_{self.saved:04d}_{host}_{path}.json"
        record = {
            "url": flow.request.pretty_url,
            "method": flow.request.method,
            "status": flow.response.status_code,
            "content_type": ctype,
            "body": body,
        }
        out = Path(ctx.options.json_dir) / name
        out.write_text(json.dumps(record, indent=2, ensure_ascii=False), encoding="utf-8")
        logger.info("Saved %s -> %s", flow.request.pretty_url, out)


addons = [SaveJSON()]

Details that matter: response.json() decodes gzip, Brotli and other content encodings before parsing, raises JSONDecodeError (a ValueError) for invalid JSON and TypeError when the body was streamed and isn’t available. Turning a bad filter into OptionsError gives a clean error message instead of a traceback. Options set with --set before the script loads are deferred and applied once load() registers them.

Answering requests from the proxy

If you set flow.response inside request(), mitmproxy replies itself and never contacts the server; the official http-reply-from-proxy.py example uses the same technique. That is handy when a debugging session goes through a metered proxy and you don’t need images or fonts:

Example 6 — block_assets.py: answer heavy asset requests locally (Python)
"""block_assets.py: answer image, font and media requests locally."""
import logging

from mitmproxy import http

logger = logging.getLogger(__name__)

HEAVY = (".png", ".jpg", ".jpeg", ".gif", ".webp", ".avif", ".svg",
         ".woff", ".woff2", ".ttf", ".mp4", ".webm")


class BlockAssets:
    def __init__(self) -> None:
        self.blocked = 0

    def request(self, flow: http.HTTPFlow) -> None:
        path = flow.request.path.split("?")[0].lower()
        if path.endswith(HEAVY):
            # Setting a response here means the request never leaves mitmproxy.
            flow.response = http.Response.make(204)
            self.blocked += 1

    def done(self) -> None:
        logger.info("Blocked %d asset requests", self.blocked)


addons = [BlockAssets()]

Pages may render differently without assets. mitmproxy also has a built-in block_list option (/flow-filter/status-code) for simple cases that don’t need code.

mitmdump for Headless Capture

Record now, analyze later

mitmdump is what you run on a server, in CI or next to a long scraping job. Three flags do most of the work: -s loads addons, -w PATH streams every flow to a file (prefix the path with + to append), and -r PATH reads a saved file back. A filter expression at the end of the command limits both what is printed and what is saved.

Example 7 — record, filter and replay flows with mitmdump (Bash)
# Record everything, save JSON responses from one domain as files
mitmdump --listen-host 127.0.0.1 -w flows.mitm \
  -s save_json.py --set json_filter="~d example.com"

# Later: read the file without starting a proxy (-n), show headers too
mitmdump -n -r flows.mitm --flow-detail 2 "~d example.com & ~ts json"

# Open the same recording in the web UI
mitmweb -n -r flows.mitm

--flow-detail runs from 0 (silent) to 4 (full bodies, nothing truncated); the default is 1, which prints the URL and status code. -n is --no-server: process the file without listening for traffic. Running an addon with -n -r tests it against a recording without sending a request.

mitmproxy Upstream Proxy: Chaining Through ProxyEmpire

Inspect locally, exit through a residential IP

Upstream mode turns mitmproxy into the first hop of a two-proxy chain. Your tool connects to mitmproxy on localhost; mitmproxy decrypts and records the traffic, then forwards every request through a second proxy, which picks the exit IP the target site sees. The background on multi-hop setups is in our proxy chaining guide.

Figure 1 — mitmproxy in upstream mode with a ProxyEmpire gateway
your tool (curl, requests, Playwright)
   |  plain proxy, no auth, trusts mitmproxy CA
   v
mitmproxy  127.0.0.1:8080   --mode upstream:...
   |  decrypts, records, runs addons
   |  CONNECT + Proxy-Authorization (from --upstream-auth)
   v
v2.proxyempire.io:5000   (residential or mobile exit IP)
   |
   v
target site  (sees the ProxyEmpire IP; TLS verified by mitmproxy)

Two options do it. --mode upstream:http://v2.proxyempire.io:5000 names the upstream proxy; its scheme must be http or https, and the address can’t contain credentials, since the mode parser accepts only scheme, host and port. Credentials go in --upstream-auth, formatted username:password. mitmproxy turns that into a Proxy-Authorization: Basic header on the CONNECT it sends upstream for HTTPS, and on each request for plain HTTP.

For ProxyEmpire, open Proxy Manager → Connection Builder in the dashboard, choose the location and rotation, and copy the generated username and your password. Pick Same IP (a sticky session) while debugging, so every flow in a capture shares one exit IP and comparisons between requests are meaningful. Our sticky vs rotating proxies article explains when to switch to per-request rotation.

Example 8 — mitmweb in upstream mode through ProxyEmpire, then a check (Bash)
# Values copied from Proxy Manager -> Connection Builder
export PE_USER='USERNAME'
export PE_PASS='PASSWORD'

mitmweb --listen-host 127.0.0.1 --listen-port 8080 \
  --mode upstream:http://v2.proxyempire.io:5000 \
  --upstream-auth "$PE_USER:$PE_PASS"

# In another terminal: the IP shown is the ProxyEmpire exit, not yours
curl --proxy http://127.0.0.1:8080 \
  --cacert ~/.mitmproxy/mitmproxy-ca-cert.pem \
  https://api.ipify.org

Command-line values are visible in your shell history and the system’s process list. For anything longer-lived, put the settings in ~/.mitmproxy/config.yaml, which all three tools read at start-up, and restrict the file’s permissions:

Example 9 — the same setup in ~/.mitmproxy/config.yaml (YAML)
listen_host: 127.0.0.1
mode:
  - upstream:http://v2.proxyempire.io:5000
upstream_auth: USERNAME:PASSWORD

Why chain at all, rather than pointing the tool straight at the gateway?

  • You see exactly what leaves your machine, decrypted, while the site sees the residential IP it would see in production. That is the fastest way to tell a proxy problem from a request problem.
  • Credentials live in one place. The tool talks to an unauthenticated proxy on localhost, which helps with clients that handle proxy authentication poorly. Chromium, for example, doesn’t support username and password on SOCKS5 proxies.
  • Addons apply to proxied traffic. Save JSON, block assets to save bandwidth, or add headers, all before the request reaches the gateway.

Some practical limits. Upstream mode talks to ProxyEmpire over HTTP, which runs on TCP, and TCP ports 80 and 443 are open by default, so non-web protocols and HTTP/3 over UDP won’t pass through this chain. ProxyEmpire’s rotating residential and mobile proxies do carry UDP for QUIC and DNS, but through SOCKS5 UDP ASSOCIATE or a MASQUE tunnel, not through mitmproxy’s upstream mode. Banking sites, payment processors and crypto exchanges are restricted by default. And because the local proxy has no password, binding it to 127.0.0.1 is what stops other machines on your network from spending your bandwidth. If a request fails with a 407 or 502, our proxy error codes reference helps locate which hop failed; mitmweb shows the upstream’s response in the flow detail.

For scraping public pages, rotating residential proxies give country, region, city, ZIP, ISP and ASN targeting through the same gateway. mitmproxy also ships an example addon, change_upstream_proxy.py in the repository’s examples/contrib folder, that picks a different upstream per request if you need to route some hosts differently.

Certificate Pinning and Other Limits

What mitmproxy can’t see by default
  • Certificate pinning. Some apps, especially mobile apps, accept only specific certificates or keys for their servers. The docs say plainly that such apps won’t accept mitmproxy’s certificates without being modified. If you don’t need that traffic, add the hosts to --ignore-hosts (a regular expression matched against the host or IP), which passes TLS through untouched. The docs mention patching tools for apps you are entitled to test; that is a security-research task outside this guide.
  • Clients with their own trust store. Java, Node.js, Firefox and Python’s requests (which uses the certifi bundle) don’t read the OS store by default. Each needs the CA added in its own way, such as an environment variable or a profile setting.
  • Clients that ignore proxy settings. Use local mode for a process on the same machine, or WireGuard mode for another device.
  • Fingerprints change. mitmproxy opens its own TLS connection to the server, so the server sees mitmproxy’s TLS handshake rather than your client’s. Sites that score TLS fingerprints may treat proxied traffic differently from direct traffic, so confirm findings with a direct request before you rely on them.
  • Memory. The interactive tools keep captured flows in memory. For long captures, use mitmdump -w and look at the file afterwards.

mitmproxy vs Charles

Free and scriptable versus paid and point-and-click

Charles is a long-established commercial debugging proxy for Windows, macOS and Linux. Both tools record and decrypt HTTPS with a locally generated root certificate, and both can chain to another proxy. The differences are in price, interface and automation:

mitmproxy 12.3.1Charles
Price and licenceFree, MIT open sourceUSD $50 per single-user licence, 30-day trial (charlesproxy.com, November 2026)
InterfaceTerminal UI, web UI and CLIDesktop GUI; separate iOS app
AutomationPython addons on every event; headless mitmdumpGUI tools such as Map Remote, Map Local, Rewrite, Breakpoints, Repeat and Block List; command-line tools are documented
Upstream proxiesupstream mode with Basic auth; per-request switching via addonExternal proxies for HTTP, HTTPS and SOCKS, with Basic and NTLM auth and a bypass list
Bandwidth throttlingNo built-in optionBuilt in
RuntimePython 3.12+, or self-contained binariesJava-based, per the Charles FAQ

For a polished GUI with throttling, Charles is comfortable and inexpensive. For captures in scripts, servers or CI, or Python logic that saves, rewrites or routes traffic, mitmproxy fits better. Many teams use both.

Responsible Use

Interception is powerful; keep it to traffic that’s yours
  • Only intercept traffic you are authorized to inspect: your own devices, applications and accounts, or systems whose owner has given you permission. Intercepting other people’s traffic can break wiretapping and computer-misuse laws.
  • Treat captures as sensitive. Flow files hold cookies, tokens and personal data in clear text. Store them like credentials and delete them when done.
  • Respect the sites you study. Finding a JSON endpoint doesn’t give you permission to hammer it. Follow the terms of service and robots.txt, keep request rates modest, back off on 429s, and use an official API where one exists.
  • Don’t use it to defeat access controls. Logged-in areas you haven’t been granted, paywalls and pinned apps you don’t own are out of bounds.

mitmproxy shows you what your own software is saying. That is a debugging tool, not a licence to read anyone else’s traffic.

Troubleshooting mitmproxy

The problems you will hit first
SymptomLikely causeFix
Certificate errors in the clientClient doesn’t trust the mitmproxy CAVisit mitm.it through the proxy, or pass mitmproxy-ca-cert.pem to the client
CA changes after a Docker restart~/.mitmproxy not mountedMount it with -v ~/.mitmproxy:/home/mitmproxy/.mitmproxy
App works without proxy, fails with itCertificate pinningAdd the host to --ignore-hosts
407 from upstreamMissing or wrong --upstream-authRecopy username and password from the Connection Builder; quote the value in the shell
No flows appearClient bypasses the proxyCheck the client’s proxy setting, or use local mode
Port already in use at start-upPort 8080 or 8081 takenUse --listen-port or --set web_port=...
pip can’t find a recent versionPython older than 3.12Use the binaries, Homebrew or uv tool install mitmproxy

Frequently Asked Questions

mitmproxy in short
What is mitmproxy used for?

Inspecting and modifying HTTP and HTTPS traffic from software you control: debugging APIs and mobile apps, finding the JSON endpoints behind web pages, testing how clients handle changed responses, and recording traffic for later analysis.

What is the difference between mitmproxy, mitmweb and mitmdump?

They share one core. mitmproxy is a terminal UI, mitmweb is a browser UI on port 8081, and mitmdump is a non-interactive command-line tool for scripts, servers and addons.

How do I use mitmproxy with an upstream proxy that needs a password?

Run mitmdump --mode upstream:http://host:port --upstream-auth username:password. Credentials can’t go in the mode URL. With ProxyEmpire the host is v2.proxyempire.io:5000 and the username comes from the Connection Builder.

Is it safe to install the mitmproxy certificate?

It is as safe as your control of ~/.mitmproxy/mitmproxy-ca.pem. Anyone with that key can impersonate any site to a device that trusts the CA. Trust it per client where you can, and remove it when you finish.

Which Python version does mitmproxy need?

mitmproxy 12.3.1 on PyPI requires Python 3.12 or newer. The standalone binaries and the Docker image include their own runtime.

Inspect locally, exit through a real residential IP

Put ProxyEmpire behind mitmproxy’s upstream mode to debug scrapers exactly as they run in production, with sticky sessions and country, city and ISP targeting through one authenticated gateway.

ProxyEmpire proxy types and prices

ProxyEmpire

Proxies for data collection at scale.

Residential, mobile, ISP and datacenter proxies for scraping, ad verification, SEO monitoring and multi-account work. Choose from 30M+ ethically sourced residential IPs and 4M+ 4G/5G mobile IPs in 170+ countries, target by country, city, ZIP, ISP or carrier, and connect over HTTP(S) or SOCKS5 with 99.9% uptime. Try residential and mobile proxies for $1.97.

🏘️ Rotating Residential Proxies
  • 30M+ Premium Residential IPs
  •  170+ Countries
    Every residential IP in our network corresponds to an actual desktop device with a precise geographical location. Our residential proxies are fast and reliable, with 99.9% uptime, and work for a wide range of use cases. You can use country, region, city, ZIP, ISP, ASN and OS fingerprint targeting for our rotating residential proxies, at no extra charge.

See our Rotating Residential Proxies

📍 Static Residential Proxies
  • 24 Countries
    Buy a dedicated static residential IP from one of the 24 countries that we offer proxies in. Keep the same IP for a month or longer, while benefiting from their fast speed and stability.

See our Static Residential Proxies

📳 Rotating Mobile Proxies
  • 4M+ Premium Mobile IPs
  •  170+ Countries
    Access millions of clean mobile IPs with precise targeting by country, region, city, ZIP, mobile carrier, ASN and OS fingerprint, at no extra charge. Get far fewer IP blocks and CAPTCHAs with our 4G and 5G proxies.

See our Mobile Proxies

📱 Dedicated Mobile Proxies
  • 4 Countries
  • 50+ Locations
    Get your own dedicated mobile proxy in one of our supported locations, with unlimited bandwidth and unlimited IP changes on demand. A great choice when you need a small number of mobile IPs and a lot of proxy bandwidth.

See our 4G & 5G Proxies

🌐 Rotating Datacenter Proxies
  • 197,000+ IPs Premium IPs
  •  62 Countries
    On a budget and need to do some simple scraping tasks? Our datacenter proxies are the perfect fit! Get started with as little as $2

See our Datacenter Proxies

♾️ Unlimited Residential Proxies
  • 1M+ Daily Residential IPs
  • 85+ Countries
    Our unlimited residential proxies bill by connection speed, not gigabytes: 100 to 1000 Mbit with unlimited bandwidth, on daily, weekly or monthly plans. Ask us for a 1-hour trial at 50 Mbit before you pick a plan.

See our Unlimited Residential Proxies

proxy locations

30M+ rotating IPs

99.9% uptime - high speed

99.9% uptime.

dedicated support team

24/7 Dedicated Support.

fair price

Fair Pricing.

🏠 Residential Proxies Rotating / Static / Unlimited
📱 Mobile Proxies Rotating and Dedicated
🖥️ Datacenter Proxies Rotating
🌍 IP Pool 30M+ residential + 4M+ mobile IPs
📶 Uptime 99.9% · Live status
💳 Payment Card · PayPal · Crypto · Bank transfer
💬 Support 24/7 live chat · [email protected]