Skip to main content
mitmproxy is an interactive, SSL/TLS-capable intercepting proxy with support for HTTP/1, HTTP/2, and WebSockets. This guide covers all installation methods across different platforms.

​
System Requirements

Before installing mitmproxy, ensure your system meets these requirements:
  • Python: 3.12 or higher (for pip/pipx installations)
  • Operating System: macOS, Linux, or Windows
  • Memory: 512MB RAM minimum (1GB+ recommended)
  • Storage: ~100MB for binary packages
The standalone binaries include a self-contained Python environment and all dependencies, so you don’t need Python pre-installed for those installation methods.

​
Installation Methods

1
Choose Your Platform
2
Select the installation method that best fits your operating system and use case:
3
macOS

​
macOS Installation

The recommended way to install mitmproxy on macOS is using Homebrew:
brew install --cask mitmproxy
After installation, verify it works:
mitmproxy --version
mitmdump --version
mitmweb --version
All three tools are included: mitmproxy (interactive CLI), mitmdump (command-line), and mitmweb (web interface).

​
Alternative: Standalone Binaries

Download the latest binary from mitmproxy.org:
  1. Download the .tar.gz file for macOS
  2. Extract: tar -xzf mitmproxy-*-macos.tar.gz
  3. Move to PATH: sudo mv mitmproxy mitmdump mitmweb /usr/local/bin/
Linux

​
Linux Installation

The recommended way to install mitmproxy on Linux is to download standalone binaries from mitmproxy.org.
# Download and extract (replace X.X.X with version)
wget https://snapshots.mitmproxy.org/X.X.X/mitmproxy-X.X.X-linux-x86_64.tar.gz
tar -xzf mitmproxy-*-linux-x86_64.tar.gz

# Move to PATH
sudo mv mitmproxy mitmdump mitmweb /usr/local/bin/

# Verify installation
mitmproxy --version

​
Distribution Packages

Some Linux distributions provide community-maintained packages:
# Arch Linux
sudo pacman -S mitmproxy

# Debian/Ubuntu/Kali
sudo apt install mitmproxy

# Fedora
sudo dnf install mitmproxy
Distribution packages are maintained by third parties and may lag behind official releases. For the latest version, use standalone binaries.
Windows

​
Windows Installation

Download the installer from mitmproxy.org:
1

Download Installer

Download the .exe installer for Windows from the official website.
2

Run Installer

Run the installer - it will automatically add mitmproxy to your PATH.
3

Install Windows Terminal (Recommended)

For better console rendering, install Windows Terminal:
winget install Microsoft.WindowsTerminal
4

Verify Installation

Open a new terminal and verify:
mitmproxy --version
mitmdump --version
mitmweb --version

​
WSL (Windows Subsystem for Linux)

All mitmproxy tools are fully supported under WSL. After installing WSL, follow the Linux installation instructions above.
pip/pipx

​
Installation from PyPI

If you need to install additional Python packages for custom addons, install from PyPI.
# Install pipx if you don't have it
python3 -m pip install --user pipx
python3 -m pipx ensurepath

# Install mitmproxy
pipx install mitmproxy

# Install with additional dependencies
pipx install mitmproxy --include-deps
pipx inject mitmproxy your-package-name

​
Using uv (Modern Alternative)

uv is a fast Python package installer:
# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install mitmproxy
uv tool install mitmproxy

# Install with additional packages
uv tool install --with your-package-name mitmproxy

​
Using pip

pip install mitmproxy
Installing with pip into your global Python environment is not recommended. Use pipx or uv instead.
Docker

​
Docker Installation

Use the official mitmproxy images from DockerHub:
# Pull the latest image
docker pull mitmproxy/mitmproxy:latest

# Run mitmweb (web interface)
docker run --rm -it -p 8080:8080 -p 8081:8081 \
  mitmproxy/mitmproxy mitmweb --web-host 0.0.0.0

# Run mitmdump
docker run --rm -it -p 8080:8080 \
  mitmproxy/mitmproxy mitmdump

​
Persist Certificate Authority

To avoid regenerating the CA certificate on each run:
docker run --rm -it -p 8080:8080 \
  -v ~/.mitmproxy:/home/mitmproxy/.mitmproxy \
  mitmproxy/mitmproxy mitmweb --web-host 0.0.0.0

​
Mount Custom Scripts

docker run --rm -it -p 8080:8080 \
  -v $(pwd)/scripts:/home/mitmproxy/scripts \
  mitmproxy/mitmproxy mitmdump -s /home/mitmproxy/scripts/addon.py
4
Development Installation
5
For contributing to mitmproxy or installing from source:
6
1

Install uv

Install the uv package manager:
curl -LsSf https://astral.sh/uv/install.sh | sh
1

Clone Repository

Clone the mitmproxy repository:
git clone https://github.com/mitmproxy/mitmproxy.git
cd mitmproxy
1

Run from Source

Use uv run to automatically set up the environment:
uv run mitmproxy --version
uv run mitmdump --version
uv run mitmweb --version
This creates a virtual environment in .venv and installs all dependencies automatically.
1

Activate Environment (Optional)

To run commands without uv run prefix:
# Linux/macOS
source .venv/bin/activate

# Windows
.venv\Scripts\activate

# Now run directly
mitmproxy --version
7
For more development details, see CONTRIBUTING.md on GitHub.

​
Verifying Installation

After installation, verify all three tools are available: 
# Check versions
mitmproxy --version
mitmdump --version
mitmweb --version

# Quick test - start mitmdump
mitmdump
You should see output indicating mitmproxy is listening on http://localhost:8080. Press Ctrl+C to stop.

​
Dependencies

For reference, mitmproxy requires these key Python dependencies: 
# Core dependencies (from pyproject.toml)
requires-python = ">=3.12"

dependencies = [
    "aioquic>=1.2.0,<=1.2.0",
    "asgiref>=3.2.10,<=3.11.0",
    "brotli>=1.0,<=1.2.0",
    "certifi>=2019.9.11",
    "cryptography>=42.0,<=46.1",
    "flask>=3.0,<=3.1.2",
    "h2>=4.3.0,<=4.3.0",
    "pyOpenSSL>=24.3,<=25.3.0",
    "tornado>=6.5.0,<=6.5.4",
    "urwid>=2.6.14,<=3.0.3",
    # ... and more
]
Binary packages include all dependencies pre-compiled. You only need to worry about dependencies if installing via pip/pipx.

​
Security Considerations

Binary packages include frozen dependency versions. Always update regularly to get security fixes:
# Homebrew
brew upgrade mitmproxy

# pip/pipx
pipx upgrade mitmproxy

# Check for updates
mitmproxy --version
  • Binary packages include a self-contained Python environment and OpenSSL
  • Dependencies are frozen at release time and cannot be updated in-place
  • Update mitmproxy regularly to ensure all dependencies remain current
  • mitmproxy does not “phone home” or perform automatic update checks

​
Troubleshooting

Linux/macOS: Ensure the binary location is in your PATH:
echo $PATH
export PATH="$PATH:/usr/local/bin"
Windows: Restart your terminal after installation to refresh PATH.
mitmproxy requires Python 3.12+:
python3 --version
If your version is too old, either:
  • Use standalone binaries (include Python)
  • Upgrade your Python installation
If you get permission errors:
# Don't move to /usr/local/bin, use local bin instead
mkdir -p ~/.local/bin
mv mitmproxy mitmdump mitmweb ~/.local/bin/
export PATH="$PATH:~/.local/bin"
If you encounter SSL errors, ensure you have the latest CA certificates:
# pip installations
pip install --upgrade certifi

# Binary installations - update mitmproxy
brew upgrade mitmproxy  # macOS

​
Next Steps

Quickstart Guide

Get your first request intercepted in under 5 minutes

Configuration

Learn about mitmproxy’s configuration options

Writing Addons

Extend mitmproxy with custom Python scripts

Certificate Setup

Configure SSL/TLS certificate trust

Build docs developers (and LLMs) love

Get started for freeTalk to us