# How to Integrate Holehe as a Library in Python Applications: Complete Developer Guide

> Integrate Holehe into your Python apps! Import core functions to programmatically check email addresses across hundreds of services, bypassing the CLI. Get the complete developer guide now.

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

---

**You can integrate Holehe as a library by importing the core functions from `holehe.core`—specifically `import_submodules`, `get_functions`, and `launch_module`—to programmatically check email addresses across hundreds of services without invoking the CLI.**

Holehe is an open-source email reconnaissance tool developed by megadose that checks for account existence across social media platforms, software services, and websites. While it is commonly used as a command-line interface (CLI) tool, the repository is architected as a pure Python package, allowing you to embed its asynchronous checking engine directly into your own applications.

## Understanding the Core Architecture

The integration entry point resides in **[`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py)**, which exposes a clean public API for programmatic access. This module handles three critical responsibilities: dynamically loading service modules, preparing callable functions, and executing checks asynchronously using **trio** and **httpx**.

The primary functions you will interact with are:

- **`import_submodules(package_name)`** (lines 37-49): Walks the `holehe/modules/` directory and imports every service module dynamically.
- **`get_functions(modules, args)`** (lines 50-66): Converts imported modules into a list of callable async functions that accept `(email, client, out)` arguments.
- **`launch_module(func, email, client, out)`** (lines 66-79): Executes an individual service check within a Trio nursery, handling exceptions and appending normalized results to the shared output list.

According to the source code in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py), these utilities work together to create a uniform output dictionary for every service containing keys such as `name`, `domain`, `exists`, `emailrecovery`, `phoneNumber`, and `others`.

## Step-by-Step Integration Process

To successfully integrate Holehe into your Python application, follow this implementation pattern:

1. **Install the package** via pip: `pip install holehe`. This automatically pulls in required dependencies including `httpx`, `trio`, `beautifulsoup4`, and `termcolor` as declared in [`setup.py`](https://github.com/megadose/holehe/blob/main/setup.py).

2. **Create an async HTTP client** using `httpx.AsyncClient` with appropriate timeout settings.

3. **Load service modules** using `import_submodules("holehe.modules")` to discover all available checking functions.

4. **Retrieve callable functions** via `get_functions(modules)` to get a list of async functions representing each supported service.

5. **Execute concurrently** using `trio.open_nursery()` to schedule all service checks simultaneously, gathering results into a shared list.

## Practical Code Examples

### Minimal Async Implementation

The following example demonstrates the most direct way to integrate Holehe programmatically without CLI overhead:

```python
import trio
import httpx
from holehe.core import import_submodules, get_functions, launch_module

async def run_holehe(email: str):
    # Load every supported module from holehe/modules/

    modules = import_submodules("holehe.modules")
    services = get_functions(modules)
    
    # Initialize async HTTP client

    client = httpx.AsyncClient(timeout=10)
    results = []

    # Execute all service checks concurrently

    async with trio.open_nursery() as nursery:
        for svc in services:
            nursery.start_soon(launch_module, svc, email, client, results)

    await client.aclose()
    return sorted(results, key=lambda r: r["name"])

if __name__ == "__main__":
    email_to_check = "test@example.com"
    data = trio.run(run_holehe, email_to_check)
    for entry in data:
        print(entry)

```

This approach executes entirely in-process. The `launch_module` function catches exceptions internally and normalizes output, ensuring every result contains the same schema fields regardless of whether the service check succeeded or failed.

### Synchronous Wrapper for Blocking Applications

If your application uses synchronous code, wrap the async implementation with `asyncio.run()`:

```python
import asyncio
import httpx
from holehe.core import import_submodules, get_functions, launch_module
import trio

def check_email(email: str):
    modules = import_submodules("holehe.modules")
    services = get_functions(modules)
    client = httpx.AsyncClient(timeout=10)
    results = []

    async def _run():
        async with trio.open_nursery() as nursery:
            for svc in services:
                nursery.start_soon(launch_module, svc, email, client, results)
        await client.aclose()
        return results

    return asyncio.run(_run())

if __name__ == "__main__":
    for result in check_email("alice@sample.org"):
        print(result)

```

This pattern allows you to embed Holehe functionality into existing synchronous frameworks like Flask or Django without refactoring your entire codebase to use async/await.

### Targeting Individual Services Directly

For use cases requiring only specific platforms, import individual modules directly from `holehe.modules`:

```python
import httpx
import trio
from holehe.modules.social_media.twitter import twitter
from holehe.core import launch_module

async def check_twitter(email: str):
    async with httpx.AsyncClient() as client:
        out = []
        await launch_module(twitter, email, client, out)
        return out[0]

if __name__ == "__main__":
    print(trio.run(check_twitter, "bob@example.com"))

```

Every service module in `holehe/modules/` (such as [`holehe/modules/social_media/twitter.py`](https://github.com/megadose/holehe/blob/main/holehe/modules/social_media/twitter.py) or [`holehe/modules/software/lastpass.py`](https://github.com/megadose/holehe/blob/main/holehe/modules/software/lastpass.py)) exposes a single async function following the `(email, client, out)` signature. Using `launch_module` provides consistent error handling and result formatting identical to the full scan behavior.

## Key Implementation Details

When integrating Holehe as a library, keep these technical considerations in mind:

- **Dependency Management**: The [`setup.py`](https://github.com/megadose/holehe/blob/main/setup.py) file declares `httpx`, `trio`, `beautifulsoup4`, and `termcolor` as dependencies. Ensure these are available in your environment.

- **Output Schema**: Every service returns a standardized dictionary with the following keys: `name` (service identifier), `domain` (service domain), `exists` (boolean indicating account presence), `emailrecovery` (recovery email if exposed), `phoneNumber` (phone if exposed), and `others` (additional metadata).

- **Async Requirements**: The library relies on Trio for structured concurrency. While you can bridge to asyncio using `trio_asyncio` or similar adapters, the internal service functions require a Trio nursery for execution.

## Summary

- **Holehe functions as a Python library** through the `holehe.core` module, eliminating the need for subprocess calls.
- **Three core functions** drive the integration: `import_submodules()` for discovery, `get_functions()` for preparation, and `launch_module()` for execution.
- **All service modules** live under `holehe/modules/` and follow a uniform async signature, making them interchangeable.
- **The output schema** is consistent across all services, providing structured data about account existence and recovery information.
- **Dependencies** are minimal and standard: `httpx` for HTTP, `trio` for async concurrency, and `beautifulsoup4` for HTML parsing.

## Frequently Asked Questions

### Can I integrate Holehe without using the command-line interface?

Yes. Holehe is built as a pure Python package, so you can import `holehe.core` directly and use `import_submodules`, `get_functions`, and `launch_module` to execute checks programmatically. This approach runs entirely within your Python process without spawning shell commands.

### Is Holehe thread-safe for concurrent processing?

Holehe uses Trio for asynchronous concurrency rather than threading. Each service check runs as a separate task within a Trio nursery, sharing a single `httpx.AsyncClient` instance. For multi-threaded contexts, ensure each thread creates its own Trio event loop or use the synchronous wrapper pattern shown above.

### How do I handle rate limiting when using Holehe as a library?

The library does not implement global rate limiting internally. When integrating Holehe, you should implement your own throttling mechanisms around the `launch_module` calls or customize the `httpx.AsyncClient` instance with `limits` parameters to control connection pooling and request rates per service.

### Can I add custom services to my Holehe integration?

Yes. You can create custom modules following the same signature as existing services in `holehe/modules/` (accepting `email`, `client`, and `out` parameters) and pass them to `launch_module` directly. Alternatively, place your modules in a separate package and use `import_submodules` on your custom package path to load them alongside or instead of the default Holehe services.