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

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, 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, 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.

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:

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():

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:

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 or 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 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.

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