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

> Check a single email address with Holehe. Use the CLI tool or Python script for targeted OSINT checks. Install via pip and run holehe user@example.com.

- Repository: [Palenath/holehe](https://github.com/megadose/holehe)
- Tags: how-to-guide
- Published: 2026-08-22

---

**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`](https://github.com/megadose/holehe/blob/main/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`](https://github.com/megadose/holehe/blob/main/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`](https://github.com/megadose/holehe/blob/main/holehe/__main__.py) and registered as the `holehe` entry point in [`setup.py`](https://github.com/megadose/holehe/blob/main/setup.py).

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

```bash

# 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`](https://github.com/megadose/holehe/blob/main/holehe/core.py) and pass your target email address. This method executes all 120+ service modules asynchronously using Trio:

```python
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`](https://github.com/megadose/holehe/blob/main/holehe/modules/social_media/twitter.py) and invoke its async function directly. This approach reduces execution time and API noise:

```python
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`](https://github.com/megadose/holehe/blob/main/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`](https://github.com/megadose/holehe/blob/main/holehe/modules/mails/google.py) or [`holehe/modules/social_media/twitter.py`](https://github.com/megadose/holehe/blob/main/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`](https://github.com/megadose/holehe/blob/main/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`](https://github.com/megadose/holehe/blob/main/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`](https://github.com/megadose/holehe/blob/main/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`](https://github.com/megadose/holehe/blob/main/holehe/core.py) and executes only the requested service check.