.. _faq: 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 :doc:`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: - `mailcat `_ - `holehe `_ - `user-scanner `_ Online services: - `Noimosiny `_ - `OSINT Industries `_ - `Epieos `_ Note: if Maigret has already found an account for a username, it often extracts the linked email from the profile page automatically — see :ref:`extracting-information-from-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): :doc:`tor-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}.`` 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``. .. code-block:: console maigret --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/`` 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? --------------------------- .. code-block:: console maigret --web 5000 Then open http://127.0.0.1:5000. Screenshots and a full walkthrough are in :ref:`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: .. code-block:: console pip install 'maigret[pdf]' maigret --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 :doc:`installation`. For other report formats (``--html``, ``--md``, ``--json``, ``--csv``, ``--txt``, ``--xmind``), see :doc:`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: .. code-block:: console python3 -m maigret - ``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: .. code-block:: console pipx install maigret - On Windows, reopen the terminal after installing (``PATH`` is only read at startup), or use the standalone ``maigret_standalone.exe`` — see :doc:`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: .. code-block:: console 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 :doc:`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 `_.