How to Check a Single Email Address with Holehe: CLI and Python Guide

To check a single email address with Holehe, install the tool via pip and run holehe user@example.com in your terminal, or programmatically import the core engine from holehe/core.py to execute targeted or full-suite OSINT checks.

Holehe is a Python-based OSINT tool that verifies whether an email address is registered across more than 120 online services. Whether you need a quick command-line check or want to integrate email verification into your own Python applications, the megadose/holehe repository provides both a streamlined CLI and a flexible async API for single-email investigations.

How Holehe Validates a Single Email Address

When you submit a single email address, Holehe's core engine (holehe/core.py) orchestrates an asynchronous verification workflow. The engine instantiates an httpx.AsyncClient for HTTP requests, dynamically imports every service module located under holehe/modules/, and invokes each module's async function with the target email.

Each module executes service-specific checks—such as password recovery flows—and returns a standardized dictionary containing fields like exists, rateLimit, emailrecovery, and phoneNumber. The core aggregator collects these results and either prints them to the console (CLI mode) or returns them to your Python application.

Checking a Single Email via Command Line

The fastest way to check a single email address with Holehe is through the command-line interface defined in holehe/__main__.py and registered as the holehe entry point in setup.py.

Install the tool and run your target email as the sole argument:

# Install Holehe from PyPI

pip install holehe

# Check a single email address

holehe test@example.com

The CLI automatically initializes the core runner, executes all enabled modules, and displays a formatted table showing which services have registered accounts associated with that email, along with any recovered metadata like partial phone numbers or secondary email hints.

Checking a Single Email Programmatically with Python

For integration into custom workflows, you can embed Holehe's verification logic directly into your Python scripts. The repository provides two primary approaches: running the complete module suite or targeting specific services.

Running the Full Module Suite

To replicate the CLI behavior within Python, import the run function from holehe/core.py and pass your target email address. This method executes all 120+ service modules asynchronously using Trio:

import trio
from holehe.core import run

async def check_email_full():
    # Checks against all enabled modules

    await run("test@example.com")

trio.run(check_email_full)

Targeting a Specific Service

If you only need to verify registration on a specific platform—such as Twitter—import the individual module from holehe/modules/social_media/twitter.py and invoke its async function directly. This approach reduces execution time and API noise:

import trio
import httpx
from holehe.modules.social_media.twitter import twitter

async def check_single_service():
    email = "test@example.com"
    results = []
    client = httpx.AsyncClient()
    
    # Call the specific module

    await twitter(email, client, results)
    
    await client.aclose()
    print(results)  # [{'name': 'twitter', 'exists': True, 'emailrecovery': None, ...}]

trio.run(check_single_service)

This pattern requires manually managing the httpx.AsyncClient and a shared results list, mirroring how the core engine handles dependency injection across modules.

Core Architecture and Module Structure

Holehe's extensibility relies on a modular architecture where each online service implements a consistent interface. The holehe/core.py file contains the run() function that:

1. Discovers modules dynamically from the holehe/modules/ directory tree
2. Instantiates a shared httpx.AsyncClient for connection pooling
3. Dispatches concurrent requests to each module's async function
4. Aggregates results into a standardized format

Individual modules like holehe/modules/mails/google.py or holehe/modules/social_media/twitter.py implement service-specific logic for determining account existence, typically by analyzing password reset endpoints or login form responses.

Summary

• CLI Method: Run holehe user@example.com after pip installation to check a single email across all supported services via the entry point in setup.py.
• Python Full Suite: Import run from holehe.core and execute await run("email@example.com") within a Trio async context to programmatically trigger complete verification.
• Python Targeted: Import specific modules (e.g., from holehe.modules.social_media.twitter import twitter) to check individual services, manually passing an httpx.AsyncClient and results list.
• Core Engine: The holehe/core.py orchestrator handles async HTTP client management, module discovery, and result standardization for every verification request.
• Output Format: Results include boolean exists flags, rateLimit indicators, and recovery metadata like emailrecovery or phoneNumber hints when available.

Frequently Asked Questions

Can I check a single email address without installing Holehe?

No, Holehe requires local installation via pip to function. The tool executes live HTTP requests against 120+ services using async Python code, which necessitates installing the package and its dependencies (including httpx and trio) in your environment.

What information does Holehe return when checking an email?

Holehe returns standardized dictionaries from each service module containing an exists boolean indicating account registration, a rateLimit boolean for throttling status, and optional fields like emailrecovery or phoneNumber that may reveal partial account recovery information.

Why does Holehe use Trio for asynchronous operations?

Holehe uses Trio (via trio.run()) to manage concurrent async HTTP requests across all service modules efficiently. The holehe/core.py engine relies on httpx.AsyncClient for connection pooling, and Trio provides the structured concurrency needed to run dozens of verification checks simultaneously without blocking.

How do I check just one specific service instead of all 120+?

Import the specific module directly from holehe/modules/ (e.g., from holehe.modules.mails.google import google) and call its async function with an httpx.AsyncClient, the target email, and a results list. This bypasses the full orchestration in holehe/core.py and executes only the requested service check.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}