Guide · Open source
How to use mitmproxy: intercept and inspect web traffic
Updated · written with AI from the project's own documentation and checked against our catalogue data
mitmproxy is an open-source proxy that sits between a device or app and the internet, letting you see the requests and responses passing through, including encrypted HTTPS (TLS) traffic. This guide explains what its three interfaces do, how to get it running from the project's repository, and what to check before you intercept anything. By the end you will know which interface suits your task and how to approach a first capture.
mitmproxymitmproxy/mitmproxy · ★ 46.6k · MIT Install options & downloads Quick start
- 1Check prerequisites. Install Python using the version listed on the project's PyPI page.
- 2Get the source. Clone the mitmproxy repository from GitHub using the command shown in this guide.
- 3Read the installation docs. Open docs.mitmproxy.org/stable/overview-installation for the setup steps for your system.
- 4Choose an interface. Pick mitmproxy for the console, mitmdump for the command line, or mitmweb for a browser view.
- 5Point your client at the proxy. Configure the device or app you want to inspect to send traffic through the proxy, using the settings in the official docs.
- 6Trust the certificate for HTTPS. Install and trust the proxy's certificate on the client so encrypted traffic can be read, following the official guide.
- 7Review and act on traffic. Inspect the captured requests and responses, and only on systems you are permitted to test.
What mitmproxy is and which interface to pick
mitmproxy is an interactive, SSL/TLS-capable intercepting proxy for HTTP/1, HTTP/2 and WebSockets. The project ships three tools: mitmproxy, which provides a console interface; mitmdump, the command-line version that the project describes as tcpdump for HTTP; and mitmweb, a web-based interface.
- mitmproxy: interactive console view of intercepted traffic.
- mitmdump: command-line tool for scripting or automating traffic handling.
- mitmweb: browser-based view of intercepted traffic.
Install mitmproxy from the repository
The project's README points to its documentation for installation instructions, and says that installing from source is covered in CONTRIBUTING.md. The one install command the source gives is cloning the repository. The prerequisite listed is Python, with the supported version shown on the project's PyPI page.
Check the official installation page at docs.mitmproxy.org for the exact steps for your system before running anything else.
- Install Python, using the version listed on the project's PyPI page.
- Clone the repository to get the source.
git clone https://github.com/mitmproxy/mitmproxyStart a capture and view traffic
Start one of the three interfaces, then point the client you want to inspect at the proxy. The README does not give the default listening address or port, so confirm those in the official documentation before configuring your device or app.
Once traffic flows through the proxy, each request and response appears in the interface you chose. Use the console for interactive browsing, mitmdump when you want output you can script, and mitmweb when you prefer a browser view.
- Use mitmproxy for an interactive console session.
- Use mitmdump to process traffic from the command line.
- Use mitmweb to browse captured traffic in a browser.
Inspect encrypted HTTPS traffic
mitmproxy is described as TLS-capable, so it can handle encrypted HTTPS connections, not only plain HTTP. Seeing decrypted HTTPS content generally requires the client to trust the proxy's certificate. The source does not detail the certificate steps, so follow the mitmproxy documentation for that setup.
Only intercept traffic you own or have permission to inspect. The project notes that it is designed to break open encrypted connections.
Use mitmproxy for debugging and testing
The most common uses are debugging how an app talks to a backend API and inspecting traffic from a client application during a penetration test. Developers can check request headers and response bodies, while people who want to automate changes to web traffic can script them with the command-line tool.
- Debug how a mobile or desktop app calls a backend API.
- Inspect the requests a client application sends during an authorised penetration test.
- Script changes to web traffic with mitmdump.
- Review captured traffic in a browser with mitmweb.
When mitmproxy is the wrong tool
If you only need to see requests from a web page, your browser's built-in developer tools may cover it with less setup. mitmproxy is most useful when you need to inspect traffic from something other than the browser, or when you want to script it.
What people use it for
- Debugging how a mobile app calls its backend API.
- Inspecting traffic from a client application during a penetration test.
- Scripting automated changes to web traffic with mitmdump.
- Reviewing captured requests in a browser with mitmweb.
Frequently asked questions
Is mitmproxy free?
mitmproxy is released under the MIT licence and its source is on GitHub. The MIT licence is a permissive open-source licence, so check its terms if you plan to reuse the code.
What language is mitmproxy written in?
The project is written in Python. Python is listed as the prerequisite for installing it, with the supported version shown on the project's PyPI page.
Can mitmproxy read HTTPS traffic?
Yes. mitmproxy is described as TLS-capable and can intercept encrypted connections. It is designed to break open those connections, so only use it on traffic you own or have permission to inspect.
Which protocols does mitmproxy support?
The README says it supports HTTP/1, HTTP/2 and WebSockets.
How is mitmproxy different from Burp Suite or OWASP ZAP?
mitmproxy is a command-line and console-first intercepting proxy with scripting through mitmdump, while Burp Suite, OWASP ZAP, Charles Proxy and Fiddler are comparable projects you could also evaluate. Pick based on whether you need scripting, a GUI or a penetration testing suite.
Where can I get help if something does not work?
The README directs questions about using mitmproxy to GitHub Discussions, and points to the documentation on docs.mitmproxy.org.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
mitmproxy suits developers debugging app and API traffic, penetration testers inspecting client applications with permission, and anyone who wants to script web traffic changes from the command line. If you only need a quick look at browser requests, your browser's developer tools are simpler, and you should not use mitmproxy on traffic you are not allowed to inspect.
Install options & downloads