FAQ

Short answers to the questions users most often type into the docs search. For deeper coverage each section links to the relevant page.

Can I search by email address?

No. Maigret only takes a username (or one of the supported identifier types) as input — searching by an email or mail address is out of scope. Looking up a mail address requires different techniques (probing password-reset flows, registration endpoints) and is the job of a separate class of tool.

Recommended open-source tools for email lookup:

Online services:

Note: if Maigret has already found an account for a username, it often extracts the linked email from the profile page automatically — see Extraction of information from account pages.

Can I configure a proxy / SOCKS / Tor / I2P?

Yes. Three flags cover three distinct goals:

--proxy URL — route every check through the given HTTP or SOCKS proxy (also the right flag for routing the whole run through Tor with socks5://127.0.0.1:9050, a residential proxy, or a corporate gateway).
--tor-proxy URL — used only for .onion sites in the database. Clearweb sites still go via your direct connection (or --proxy if set).
--i2p-proxy URL — same idea, only for .i2p hosts.

The most common confusion is --proxy vs --tor-proxy: --proxy is “everything through this gateway”, --tor-proxy is “only onion sites through Tor”.

Full walkthrough (Tor Browser vs system tor port numbers, Tails OS, timeout / retry tuning): Tor, I2P, and proxies.

If your goal is actually “bypass WAF blocks / fix 403 errors”, see the Sites fail / timeout / 403 section below — a residential proxy almost always outperforms Tor or a VPN for that.

Can I use a VPN with Maigret?

Yes, but --proxy is usually a better choice. A VPN works transparently at the OS level — Maigret needs no special configuration to use one. However:

--proxy is per-process: it does not affect other apps and does not leak when toggled.
--proxy makes the egress IP visible in logs, which is useful when diagnosing why a batch of sites returned UNKNOWN.
--proxy accepts a different value per run, so you can rotate between residential and datacenter exits without touching system network settings.

If a lot of sites are returning 403, the cause is almost certainly that the VPN exit IP is on a WAF blocklist (Cloudflare, DDoS-Guard, Akamai all blanket-block common VPN ranges). A residential proxy via --proxy is the usual fix — see the “Lots of sites fail / timeout / return 403” section in TROUBLESHOOTING.md.

Does Maigret check domains via DNS?

Yes, experimentally. With --with-domains Maigret resolves a small set of {username}.<tld> patterns through DNS (A-records) in parallel with the normal HTTP checks. The current set is .ddns.net, .com, .pro, .me, .biz, .email, .guru — 7 entries in the database with protocol: dns.

maigret <username> --with-domains

The flag is marked experimental: DNS-only checks can flag parking domains and catch-all wildcards as if the username were registered, so treat hits as a lead rather than confirmation.

If your task is wider DNS reconnaissance — subdomain enumeration, WHOIS history, typo-squatting — Maigret is the wrong tool. Established alternatives:

dnstwist — typo-squatting and look-alike domains.
amass / subfinder — subdomain enumeration.
theHarvester — email / host / subdomain harvesting by domain.

Is there a Maigret Telegram bot?

Yes. A community-maintained bot lets you run Maigret without installing anything locally:

Working instance: sites.google.com/view/maigret-bot-link (redirect — the hosted bot may move between providers).
Source code: github.com/soxoj/maigret-tg-bot.

On the question of searching Telegram itself: Maigret checks whether a t.me/<user> page exists as part of the normal run, but it does not parse channels, posts, members, or message contents. For Telegram content OSINT you need a dedicated tool.

Where is the web interface?

maigret --web 5000

Then open http://127.0.0.1:5000. Screenshots and a full walkthrough are in Web Interface.

Sites fail / timeout / return 403 — connection failures

This is the most common report and is almost always caused by anti-bot protection (Cloudflare, DDoS-Guard, Akamai) or a slow link, not by a bug in Maigret. Quick tweaks, in order:

--timeout 60 — the default 30 s is tight for slow networks and for Tor.
--retries 2 — covers transient failures.
-n 20 — lower concurrency reduces WAF rate-limiting.
--proxy http://user:pass@residential-proxy:port — datacenter IPs (AWS, GCP, DigitalOcean) and most VPN ranges are blanket-blocked; residential / mobile exits usually fix the bulk of 403s.

The full troubleshooting matrix (per-error recipes for 403, timeout, SSL, captcha, UNKNOWN floods) lives in TROUBLESHOOTING.md.

How do I generate a PDF report?

PDF support is an optional extra because it pulls heavy graphics dependencies:

pip install 'maigret[pdf]'
maigret <username> --pdf

On Linux / macOS you also need system libraries (Pango, Cairo, GDK-PixBuf). Per-OS install steps are in the Optional: PDF reports section of Installation.

For other report formats (--html, --md, --json, --csv, --txt, --xmind), see Command line options.

`maigret: command not found`

The install succeeded but your shell can’t find the maigret launcher (you may see -bash: maigret: command not found or a not recognized message on Windows). The package is installed — only the entry-point script is not on your PATH. Fixes, in order of laziness:

Run it as a module instead — this always works if the package imported:
```
python3 -m maigret <username>
```
pip install --user puts the script in a per-user bin / Scripts directory that is often not on PATH. The cleanest fix is to install into an isolated environment that manages PATH for you:
```
pipx install maigret
```
On Windows, reopen the terminal after installing (PATH is only read at startup), or use the standalone maigret_standalone.exe — see Installation.

`error: metadata-generation-failed`

This comes from pip, not Maigret: pip could not build one of the dependencies. Almost always the build toolchain is stale or a native dependency is missing its system libraries. Try, in order:

Upgrade the toolchain and retry:

python -m pip install --upgrade pip setuptools wheel

Use a supported interpreter (Python 3.10–3.12). Bleeding-edge or end-of-life versions frequently have no prebuilt wheels, forcing a source build that then fails.
If the failing package is a native one (lxml, reportlab, _renderPM, or an error mentioning ft2build.h / cairo), you need system build dependencies — see the Troubleshooting section of Installation, or skip the compilers entirely and use Docker.

`Too many errors of type "..."`

This is Maigret’s end-of-run summary, not a crash — the run finished. It means a large share of sites failed the same way, so the fix depends on the class printed in the quotes:

Connecting failure — check your internet connection; if only a subset of sites fails, lower parallelism with -n 10.
Connecting failure (DNS) — DNS resolution failed for most sites. Try --dns-resolver threaded (often fixes Windows / VPN / corporate networks); failing that, check your VPN / firewall and consider a public resolver (1.1.1.1 or 8.8.8.8).
Request timeout — raise --timeout or switch ISP / network.
Captcha — switch to another IP address, or supply service cookies.
Bot protection / Access denied — switch IP; a residential --proxy or --cloudflare-bypass is the usual fix.
Webgate unavailable — --cloudflare-bypass is on but no solver is reachable; start FlareSolverr, or drop the flag to skip protected sites.

If most of your run is one of the last three, see the Sites fail / timeout / return 403 section above and the full TROUBLESHOOTING.md.