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:

Is there a Maigret Telegram bot?

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

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:

  1. --timeout 60 — the default 30 s is tight for slow networks and for Tor.

  2. --retries 2 — covers transient failures.

  3. -n 20 — lower concurrency reduces WAF rate-limiting.

  4. --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.