Open-source project
mitmproxy/mitmproxy avatar
mitmproxy/mitmproxy

mitmproxy: An Interactive TLS-Capable Intercepting Proxy for HTTP/1, HTTP/2, and WebSockets

GitHub describes it as An interactive TLS-capable intercepting HTTP proxy for penetration testers and software developers.. The repository metadata lists Python as its primary language. The metadata lists the MIT license. This article stays within the project description and details documented in the GitHub repository README.

46,986 stars4,986 forksPythonMIT

At a glance

What is it?
mitmproxy is a console-based intercepting proxy with a companion command-line tool (mitmdump) and a web interface (mitmweb). It targets penetration testers and developers who need to inspect and modify HTTP/1, HTTP/2, and WebSocket traffic over TLS.
Who is it for?
Adopt mitmproxy if you are a penetration tester or developer who needs an interactive, cross-platform proxy for HTTP/1, HTTP/2, and WebSockets with TLS interception, and you prefer a console or web interface over a GUI. Do not use it if you require a non-interactive daemon with minimal dependencies, or if your workflow depends on protocols beyond HTTP and WebSockets, as the README does not list those.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 1 day ago.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • mitmproxy/mitmproxy46,986 ★ · +2,304
Star history
Repository2026-08-132026-11-15
mitmproxy/mitmproxy44.7k47k

2,304 Stars in the last 94 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

What mitmproxy Solves and Who Needs It

mitmproxy addresses a specific pain: inspecting and modifying HTTP traffic that is encrypted with TLS. A normal packet capture shows you IP addresses and ports, but not the plaintext of an HTTPS request. mitmproxy sits between the client and the server, terminates the TLS connection, and lets you see and alter the traffic in real time. The README describes it as an interactive, SSL/TLS-capable intercepting proxy with a console interface for HTTP/1, HTTP/2, and WebSockets. That scope matters. It is not a general network sniffer. It is for people who work on HTTP-based protocols. The stated audience is penetration testers and software developers. A penetration tester might use it to tamper with requests during an engagement. A developer might use it to debug a mobile app's API calls or to verify that a web client sends the expected headers. The three interfaces cover different workflows: mitmproxy for a terminal UI, mitmdump for scripted or headless use, and mitmweb for a browser-based view. The README calls mitmdump 'tcpdump for HTTP', which sets the expectation that it is a command-line tool for logging and filtering, not a full interactive editor.

How the Proxy Intercepts TLS and Handles Protocols

The core mechanism is TLS termination. The proxy presents its own certificate to the client, while establishing a separate TLS connection to the upstream server. For this to work, the client must trust the proxy's certificate authority. The README does not explain the certificate setup, but the description of an SSL/TLS-capable intercepting proxy implies that mitmproxy generates a CA certificate that the user installs on the client device. The proxy then decrypts the traffic, shows it in the console, and re-encrypts it when forwarding to the server. The supported protocols are HTTP/1, HTTP/2, and WebSockets. HTTP/2 is a binary protocol, so the proxy must parse frames, not just lines. WebSockets are a different beast: they start as an HTTP upgrade and then switch to a bidirectional message stream. mitmproxy handles both, which is a practical advantage for modern web applications that use HTTP/2 and WebSockets. The README does not mention HTTP/3 or QUIC. That is a gap, because newer browsers and servers are moving to HTTP/3 over UDP.

Three Interfaces: Console, Command Line, and Web

The project ships three distinct front ends. mitmproxy is the interactive console interface. It runs in a terminal and lets you inspect flows, modify requests, and replay them, all with keyboard shortcuts. mitmdump is the command-line version. The README compares it to tcpdump, which means it is designed for logging and filtering, not for interactive editing. You can pipe its output to other tools, which makes it suitable for automated testing or CI pipelines. mitmweb provides a web-based interface. You open a browser and get a graphical view of the traffic, which can be easier to navigate than a terminal for large captures. The existence of three interfaces is a strength, but it also means you have to learn two different interaction models if you switch between mitmproxy and mitmweb. The README does not describe the feature set of each interface in detail. It only states what they are. That leaves a gap: you do not know from the README whether mitmweb supports the same editing capabilities as the console version, or whether mitmdump can do request modification via scripts. The documentation link is the place to find that out, but the README itself is thin on specifics.

Getting It Running: Installation and First Steps

The README does not include installation commands. It points to an external installation guide at docs.mitmproxy.org/stable/overview-installation. The README also mentions precompiled binaries on the mitmproxy website. So you have at least two paths: download a binary or install from source. For source installation, the README refers to CONTRIBUTING.md, which suggests that building from source requires development dependencies. The project is written in Python, and the primary language is listed as Python, so a typical source install would involve cloning the repository and running a Python package manager, but the README does not give the exact command. You should check the installation guide for your platform. Once installed, you run one of the three executables: mitmproxy, mitmdump, or mitmweb. The README gives no example invocation. That is a notable omission for a tool that is meant to be used interactively. You will need to consult the documentation to learn how to start the proxy, configure the listening port, and set up the CA certificate for your client.

Limitations and Failure Modes

Protocol coverage depends on mode. The official documentation describes HTTP/3 support in reverse proxy, local and WireGuard modes, as well as generic TCP/TLS and UDP/DTLS proxying. HTTP/3 has documented limitations, including QUIC version and implementation compatibility, so check the current protocol and mode documentation before relying on a specific setup. The TLS interception itself has a failure mode: if the client does not trust the proxy's CA certificate, the TLS handshake fails, and the connection is dropped. The README does not explain how to handle certificate pinning, which some mobile apps use. With certificate pinning, the app rejects any certificate that is not the expected one, so mitmproxy cannot decrypt the traffic without additional effort. The README is silent on this, but it is a common obstacle in penetration testing. Finally, the interactive console interface has a learning curve. The README does not describe the key bindings or commands, so a new user must read the documentation or experiment. That is not a flaw of the proxy itself, but it is a cost to adoption.

Alternatives and How They Differ

Alternatives are other intercepting proxies and packet-capture tools; the repository does not name or compare any of them.

Maintenance and Upgrade Considerations

The repository is actively maintained. The last push was on 2026-11-01, and there are recent releases: v12.3.1 on 2026-10-25, v12.3.0 on 2026-10-22, and v12.2.3 on 2026-05-12. This cadence suggests regular bug fixes and feature updates. The project uses GitHub Actions for continuous integration, as shown by the badges in the README, and it has a code coverage badge, which indicates a test suite. For adoption, this means you can expect updates, but you also need to track them. The license is MIT, which is permissive. You can use it in commercial products, modify it, and redistribute it, as long as you include the original copyright notice. That is a low barrier for integration. The upgrade cost is moderate. Because the project is Python-based, upgrading via pip or replacing a binary is straightforward, but major version changes might alter the configuration format or the scripting API. The README does not provide a migration guide; the repository has a CHANGELOG.md and GitHub releases to check for each version. The presence of a dev documentation link (docs.mitmproxy.org/dev/) suggests that there is a development version with the latest changes, which is useful for testing upcoming features but also implies that you should stick to the stable documentation for production use.

Editorial conclusion

Adopt mitmproxy if you are a penetration tester or developer who needs an interactive, cross-platform proxy for HTTP/1, HTTP/2, and WebSockets with TLS interception, and you prefer a console or web interface over a GUI. Do not use it if you require a non-interactive daemon with minimal dependencies, or if your workflow depends on protocols beyond HTTP and WebSockets, as the README does not list those. Verify first that your target applications trust the mitmproxy certificate authority, and check the installation guide for your operating system, because the README points to external instructions rather than listing steps. For scripting, note that mitmdump is the command-line entry point, but the README does not detail its full API, so consult the official documentation before relying on advanced automation.

Frequently asked questions

What is MITMProxy for?

It is an interactive, SSL/TLS-capable intercepting proxy with a console interface for HTTP/1, HTTP/2 and WebSockets, and the project description positions it for penetration testers and software developers. It ships three front ends over one core, the interactive console proxy, mitmdump as the command-line version, and mitmweb as a web-based interface, and it also declares topics in security, proxy servers, network monitoring and software testing.

What is the difference between Mitmproxy and Mitmdump?

mitmdump is the command-line version of mitmproxy, described as tcpdump for HTTP, while mitmproxy is the interactive console interface. The classification Environment :: Console :: Curses is what decides which one you want in practice, because the console front end expects a real terminal, so continuous integration, a container without a tty, or a pipe is the situation where mitmdump is the right choice.

how to use mitmproxy web interface

mitmweb is the web-based interface for mitmproxy, and it is the front end to reach for when there is no interactive terminal, which is also the case inside a container. Its frontend lives in a top-level web/ directory separate from the mitmproxy/ package.

how to install mitmproxy

The README sends installation to the overview-installation page in the stable documentation, and says precompiled binaries are available on the mitmproxy website next to the general information and tutorials. For a source install it points at CONTRIBUTING.md. The distribution is on PyPI, and it requires Python 3.12 or newer with CPython as the only declared implementation.

Is MitM proxy safe?

The project is MIT licensed, classifies itself with the Topic :: Security classifier, and is marked Development Status :: 5 - Production/Stable, so the code is an established open source tool rather than something experimental. What makes it sensitive in use is the capability it is built for: a TLS-intercepting proxy has to issue certificates your client will trust, so its certificate material is privileged and anything that trusts it can be read, and you should scope that trust rather than installing it broadly.

What is a good alternative to Mitmproxy?

The project does not name competing tools. What it offers is a choice of front end for the same core, the interactive console proxy, mitmdump as the command-line version described as tcpdump for HTTP, and the web-based mitmweb, plus the extension route through the addons and contrib directories in the examples tree. Precompiled binaries and tutorials are published on the project website.

Official sources

  1. Official documentation
  2. Official README
  3. Project repository
  4. Release notes
Community

Where developers are discussing it

Posts on Hacker News, dev.to and Lobsters that link to this repository, found by our scan of those communities. 3 in the last 30 days; newest first.

Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/mitmproxy-mitmproxy.svg)](https://hysenlabs.com/projects/mitmproxy-mitmproxy)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/mitmproxy-mitmproxy.svg)](https://hysenlabs.com/projects/mitmproxy-mitmproxy)

Was this useful?