# How to Use a Custom httpx Client with holehe in Python

> Learn to use a custom httpx client with holehe in Python. Pass your httpx.AsyncClient instance to holehe() for tailored HTTP requests.

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

---

**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`](https://github.com/megadose/holehe/blob/main/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`](https://github.com/megadose/holehe/blob/main/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`](https://github.com/megadose/holehe/blob/main/holehe/__init__.py) permits you to supply your own client instance. When provided, every checking module—such as [`holehe/modules/social_media/twitter.py`](https://github.com/megadose/holehe/blob/main/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.

```python
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`](https://github.com/megadose/holehe/blob/main/holehe/core.py).

```python
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.

```python
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.

```python
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`](https://github.com/megadose/holehe/blob/main/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`](https://github.com/megadose/holehe/blob/main/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`](https://github.com/megadose/holehe/blob/main/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`](https://github.com/megadose/holehe/blob/main/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`](https://github.com/megadose/holehe/blob/main/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.