Installation

Maigret can be installed using pip, Docker, or simply can be launched from the cloned repo. Also, it is available online via the community Telegram bot, source code of a bot is available on GitHub.

Windows Standalone EXE-binaries

Standalone EXE-binaries for Windows are located in the Releases section of GitHub repository.

Currently, the new binary is created automatically after each commit to main and dev branches.

Video guide on how to run it: https://youtu.be/qIgwTZOmMmM.

Cloud Shells and Jupyter notebooks

In case you don’t want to install Maigret locally, you can use cloud shells and Jupyter notebooks. Press one of the buttons below and follow the instructions to launch it in your browser.

Open in Cloud Shell Run on Replit Open In Colab Open In Binder

Local installation from PyPi

Maigret ships with a bundled site database. After installation from PyPI (or any other method), it can automatically fetch a newer compatible database from GitHub when you run it—see Database auto-update in Settings.

Note

Python 3.10 or higher and pip is required, Python 3.11 is recommended.

# install from pypi
pip3 install maigret

# usage
maigret username

PDF report support is shipped as an optional extra because it relies on system-level graphics libraries that pip cannot install for you. If you plan to use --pdf, install Maigret with the pdf extra:

pip3 install 'maigret[pdf]'

See Optional: PDF reports (maigret[pdf]) below for the full background on why PDF support is optional and how to fix the most common build errors.

Development version (GitHub)

git clone https://github.com/soxoj/maigret && cd maigret
pip3 install .

# OR
pip3 install git+https://github.com/soxoj/maigret.git

# usage
maigret username

# OR use poetry in case you plan to develop Maigret
pip3 install poetry
poetry run maigret

Docker

# official image of the development version, updated from the github repo
docker pull soxoj/maigret

# usage
docker run -v /mydir:/app/reports soxoj/maigret:latest username --html

# manual build
docker build -t maigret .

Troubleshooting

If you encounter build errors during installation such as cannot find ft2build.h or errors related to reportlab / _renderPM, you need to install system-level dependencies required to compile native extensions.

Debian/Ubuntu/Kali:

sudo apt install -y libfreetype6-dev libjpeg-dev libffi-dev

Fedora/RHEL/CentOS:

sudo dnf install -y freetype-devel libjpeg-devel libffi-devel

Arch Linux:

sudo pacman -S freetype2 libjpeg-turbo libffi

macOS (Homebrew):

brew install freetype

After installing the system dependencies, retry the maigret installation.

If you continue to have issues, consider using Docker instead, which includes all necessary dependencies.

Optional: PDF reports (maigret[pdf])

The --pdf report format is shipped as an optional extra. To enable it:

pip3 install 'maigret[pdf]'

If PDF support is not installed and you pass --pdf, Maigret prints a warning and continues without crashing — every other output format (--html, --json, --csv, --txt, --xmind, --graph) keeps working.

Why is PDF optional?

Maigret renders PDFs by converting an HTML template, and that conversion pipeline ultimately depends on the cairo graphics library through a chain of Python packages roughly shaped like:

maigret[pdf] → xhtml2pdf → svglib → rlPyCairo → pycairo → libcairo2 (system)

The bottom of that chain is a C library — libcairo2 — that has to exist on the host before pip can build the Python bindings. The Python binding package (pycairo) currently ships only Windows wheels on PyPI; on Linux and macOS pip falls back to building from source, and the build fails the moment pkg-config cannot find cairo. The error looks like:

../cairo/meson.build:31:12: ERROR: Dependency "cairo" not found (tried pkg-config)
note: This error originates from a subprocess, and is likely not a problem with pip.
error: metadata-generation-failed

Pulling this whole chain for every Maigret install just so the much smaller group of users who actually want PDFs can have them is a poor trade — so xhtml2pdf is gated behind the pdf extra.

Two more packages — arabic-reshaper and python-bidi — are bundled into the same extra. Maigret core never imports them; they are only used by xhtml2pdf to shape Arabic glyphs and lay out right-to-left text in PDFs. python-bidi v0.5+ is also a Rust binding, so on niche platforms without a published wheel it would otherwise pull in a Cargo build for users who never asked for PDF support.

Installing the system prerequisites

Install the cairo headers, pkg-config, and a working C toolchain before running pip install 'maigret[pdf]'.

Debian / Ubuntu / Linux Mint / Kali:

sudo apt update
sudo apt install -y libcairo2-dev pkg-config python3-dev build-essential
pip3 install --upgrade pip setuptools wheel
pip3 install 'maigret[pdf]'

Fedora / RHEL / CentOS:

sudo dnf install -y cairo-devel pkgconfig python3-devel gcc
pip3 install 'maigret[pdf]'

Arch Linux:

sudo pacman -S cairo pkgconf base-devel
pip3 install 'maigret[pdf]'

Alpine Linux:

sudo apk add cairo-dev pkgconf python3-dev build-base
pip3 install 'maigret[pdf]'

macOS (Homebrew):

brew install cairo pkg-config
pip3 install --upgrade pip setuptools wheel
pip3 install 'maigret[pdf]'

Windows:

No system packages are needed — pycairo ships prebuilt wheels for Windows. Just run:

pip install 'maigret[pdf]'

Google Cloud Shell / Colab / Replit / generic CI:

These environments behave like Debian/Ubuntu — install the same libcairo2-dev pkg-config python3-dev build-essential triple before pip install 'maigret[pdf]'. If you do not control the base image and cannot apt install, skip the extra and use --html reports instead; HTML reports contain the same data and open in any browser.

maigret: command not found after install

If pip prints warnings like:

WARNING: The scripts maigret and update_sitesmd are installed in
'/home/<user>/.local/bin' which is not on PATH.

…and maigret --version then fails with command not found, your --user install put the entry-point script in a directory the shell does not search. Add it to PATH:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Or install into a virtual environment, where the entry point lands in the venv’s bin/ automatically:

python3 -m venv ~/.venvs/maigret
source ~/.venvs/maigret/bin/activate
pip install 'maigret[pdf]'   # or just `pip install maigret`

Optional: Cloudflare bypass solver

Warning

Experimental. The Cloudflare webgate is under active development; the configuration schema and CLI behaviour may change without backwards-compatibility guarantees.

Sites tagged cf_js_challenge / cf_firewall need a real browser to pass their JavaScript challenge. To check those sites you can run a local FlareSolverr instance — Maigret will route protected checks to it when --cloudflare-bypass is set:

docker run -d -p 8191:8191 --name flaresolverr ghcr.io/flaresolverr/flaresolverr:latest

This is optional — Maigret runs without it; only sites whose protection field intersects settings.cloudflare_bypass.trigger_protection require the solver. See Cloudflare webgate bypass for details.