How to Use a Custom httpx Client with holehe in Python

To use a custom httpx client with holehe, instantiate httpx.AsyncClient with your desired configuration and pass it to the holehe() function via the client parameter; all internal modules reuse this instance for every HTTP request.

The open-source OSINT tool holehe by megadose relies on httpx for asynchronous HTTP requests across its 120+ social media checking modules. While the library automatically creates a default httpx.AsyncClient in holehe/core.py, the public API exposes a client argument that allows you to override this behavior. This guide demonstrates how to use a custom httpx client with holehe based on the actual source implementation.

How holehe Internalizes HTTP Clients

According to the source in holehe/core.py, the main orchestration logic initializes an httpx.AsyncClient with a default timeout only when no external client is supplied. However, the entry point defined in holehe/__init__.py permits you to supply your own client instance. When provided, every checking module—such as holehe/modules/social_media/twitter.py—receives the same client object via its function signature (e.g., async def twitter(email, client, out)). This architecture ensures that connection pooling, proxy settings, and header configurations propagate consistently across all services.

Creating a Custom httpx.AsyncClient

Before invoking holehe, construct an httpx.AsyncClient tailored to your network environment. The client supports proxy routing, custom headers, SSL verification toggles, and timeout specifications.

import httpx

custom_client = httpx.AsyncClient(
    timeout=20.0,
    proxies="http://127.0.0.1:8080",
    headers={"User-Agent": "MyHoleheBot/2.0"},
    verify=False
)

Passing the Client to holehe

Supply your configured client to the holehe() function. The function signature accepts client as a keyword argument and forwards it to every module it invokes, bypassing the default client creation logic in holehe/core.py.

import asyncio
from holehe import holehe

async def check_email(email: str):
    async with custom_client:
        results = await holehe(email, client=custom_client)
        return results

# Execute the check

output = asyncio.run(check_email("alice@example.com"))

When you provide a client, holehe skips its internal client instantiation and uses your instance for all GET and POST operations across modules.

Advanced Configuration Examples

Configuring Transport Adapters for Retries

For enterprise environments requiring retry logic or connection pooling limits, create a custom transport layer and attach it to your client.

import httpx
from httpx import Limits

transport = httpx.AsyncHTTPTransport(
    retries=3,
    limits=Limits(max_connections=100, max_keepalive_connections=20)
)

client = httpx.AsyncClient(transport=transport, timeout=15.0)

# Pass to holehe

import asyncio
from holehe import holehe

async def main():
    result = await holehe("target@example.org", client=client)
    await client.aclose()
    
asyncio.run(main())

Synchronous Wrapper Pattern

If your application requires a synchronous interface, wrap the async call while preserving the custom client configuration.

import asyncio
import httpx
from holehe import holehe

def sync_check(email: str):
    async def _check():
        async with httpx.AsyncClient(timeout=30.0) as client:
            return await holehe(email, client=client)
    return asyncio.run(_check())

print(sync_check("user@example.com"))

Summary

• holehe uses httpx.AsyncClient for all asynchronous HTTP requests across its modules as defined in holehe/core.py.
• The holehe() entry point accepts a client parameter that overrides the default client creation when provided.
• Supplying a custom client enables global configuration of proxies, timeouts, headers, SSL verification, and transport adapters for all checks.
• Each module function (e.g., async def twitter(email, client, out) in holehe/modules/social_media/twitter.py) receives the client instance and uses it for requests.
• Always close the client after execution using await client.aclose() or the async with context manager to prevent connection leaks.

Frequently Asked Questions

What parameter does holehe use to accept a custom httpx client?

The holehe() function accepts a client parameter where you pass your httpx.AsyncClient instance. This parameter is defined in the main entry point located in holehe/__init__.py and propagates through to every module function, ensuring all checks use your configured session.

Can I route holehe traffic through a custom proxy?

Yes. Create an httpx.AsyncClient with the proxies argument set to your proxy URL (e.g., proxies="http://127.0.0.1:8080"), then pass that client to holehe(). All requests made during the email validation process will route through your specified proxy according to the implementation in holehe/core.py.

Does holehe support synchronous execution with a custom client?

While holehe is built on async/await patterns, you can wrap the async function in asyncio.run() while still injecting a custom client. Create the client inside an async function, pass it to holehe(), and return the results to a synchronous caller without losing your connection settings.

Where is the default httpx client created if I don't provide one?

The default client initialization occurs in holehe/core.py, where the code instantiates httpx.AsyncClient(timeout=timeout) unless you provide your own client via the client parameter in the main function.

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