Library usage

Maigret’s CLI is a thin wrapper around an async Python API. You can embed Maigret in your own tools, pipelines, and OSINT workflows — no need to shell out.

This page covers the common patterns. For the full argument list of the underlying function, see maigret.checking.maigret in the source.

Installation

pip install maigret

Minimal example

A working end-to-end search against the top 500 sites:

import asyncio
import logging

from maigret import search as maigret_search
from maigret.sites import MaigretDatabase

# Load the bundled site database
db = MaigretDatabase().load_from_path(
    "maigret/resources/data.json"
)

# Pick which sites to scan (same filtering the CLI uses)
sites = db.ranked_sites_dict(top=500)

results = asyncio.run(
    maigret_search(
        username="soxoj",
        site_dict=sites,
        logger=logging.getLogger("maigret"),
        timeout=30,
        is_parsing_enabled=True,
    )
)

for site_name, result in results.items():
    if result["status"].is_found():
        print(site_name, result["url_user"])

Key points:

maigret_search is an async function — wrap it with asyncio.run(...) or await it from inside your own event loop.
is_parsing_enabled=True turns on socid_extractor so result["ids_data"] is populated with profile fields (bio, linked accounts, uids, etc.). See its Library usage page for calling it directly, and Maigret integration for how the two projects fit together.
Each entry in the returned dict has a "status" object with is_found(), plus url_user, http_status, rank, ids_data, and more.

Filtering sites

ranked_sites_dict accepts the same filters as the CLI:

# All sites tagged as coding, top 200 by rank
sites = db.ranked_sites_dict(top=200, tags=["coding"])

# Exclude NSFW and dating sites
sites = db.ranked_sites_dict(excluded_tags=["nsfw", "dating"])

# Only specific sites by name
sites = db.ranked_sites_dict(names=["GitHub", "Reddit", "VK"])

# Include disabled sites (useful for maintenance / self-check)
sites = db.ranked_sites_dict(disabled=True)

Running inside an existing event loop

If your application already runs an asyncio loop (FastAPI, aiohttp server, a Discord bot, etc.), await maigret_search directly instead of calling asyncio.run:

async def check_username(username: str) -> dict:
    results = await maigret_search(
        username=username,
        site_dict=sites,
        logger=logger,
        timeout=30,
    )
    return {
        name: r["url_user"]
        for name, r in results.items()
        if r["status"].is_found()
    }

Routing through a proxy

The same proxy / Tor / I2P flags the CLI exposes are plain keyword arguments:

results = await maigret_search(
    username="soxoj",
    site_dict=sites,
    logger=logger,
    proxy="socks5://127.0.0.1:1080",
    tor_proxy="socks5://127.0.0.1:9050",   # used for .onion sites
    i2p_proxy="http://127.0.0.1:4444",     # used for .i2p sites
    timeout=30,
)

Full function signature

async def maigret(
    username: str,
    site_dict: Dict[str, MaigretSite],
    logger,
    query_notify=None,
    proxy=None,
    tor_proxy=None,
    i2p_proxy=None,
    timeout=30,
    is_parsing_enabled=False,
    id_type="username",
    debug=False,
    forced=False,
    max_connections=100,
    no_progressbar=False,
    cookies=None,
    retries=0,
    check_domains=False,
) -> Dict[str, Any]

See Command line options for a description of each option — the semantics match the CLI flags one-to-one.