# How the Timeout Parameter Affects Module Execution and Reliability in Holehe

> Learn how the timeout parameter in Holehe balances scan speed and accuracy by setting request limits and allowing module overrides for reliable module execution.

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

---

**The `--timeout` flag in Holehe sets a global 10‑second limit on all HTTP requests, which modules can override per‑request to balance scan speed against detection accuracy.**

The `timeout` parameter is a critical tuning knob in Holehe, the open‑source asynchronous email search tool by megadose. It governs how long each module waits for a target service to respond before abandoning the attempt. By understanding how this parameter propagates through the codebase, you can optimize your scans for either speed or thoroughness depending on your network conditions and target landscape.

## Where the Timeout Parameter Is Defined and Applied

The **`-T` / `--timeout`** CLI option is parsed in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) at lines 194–199:

```python

# holehe/core.py#L194-L199

parser.add_argument(
    "-T", "--timeout",
    type=int,
    default=10,
    help="Timeout for requests (default: 10)"
)

```

This value is then passed to the shared `httpx.AsyncClient` constructor at lines 212–214:

```python

# holehe/core.py#L212-L214

client = httpx.AsyncClient(
    timeout=args.timeout,
    ...
)

```

Holehe instantiates **a single asynchronous HTTP client** that every module receives and reuses during execution. This design choice centralizes connection pooling and ensures consistent timeout behavior across the entire scan—unless a module explicitly chooses otherwise.

## How Modules Inherit or Override the Timeout

When a module runs, it uses the injected `client` object to perform its HTTP request(s). The timeout behavior follows two patterns:

- **Global inheritance**: If a module makes a request without specifying a timeout, it automatically uses the value set on the shared client.
- **Local override**: Some modules hardcode shorter timeouts for specific requests when they know a service is fast or when aggressive timing reduces detection risk.

For example, in [`holehe/modules/social_media/myspace.py`](https://github.com/megadose/holehe/blob/main/holehe/modules/social_media/myspace.py) at line 21, the module forces a 2‑second timeout:

```python

# holehe/modules/social_media/myspace.py#L21

r = await client.get(url, timeout=2)

```

Similarly, [`holehe/modules/medical/caringbridge.py`](https://github.com/megadose/holehe/blob/main/holehe/modules/medical/caringbridge.py) at line 36 uses `timeout=3`, and several forum modules like [`holehe/modules/forum/onlinesequencer.py`](https://github.com/megadose/holehe/blob/main/holehe/modules/forum/onlinesequencer.py) at line 23 and [`holehe/modules/forum/cracked_to.py`](https://github.com/megadose/holehe/blob/main/holehe/modules/forum/cracked_to.py) use `timeout=1`.

These local values **supersede** the global client timeout for that specific request, allowing fine‑grained control without affecting other modules.

## Impact on Scan Execution and Duration

Adjusting the timeout parameter creates a direct trade‑off between **speed** and **coverage**:

| Timeout Setting | Effect on Execution Time | Effect on Detection Accuracy |
|-----------------|--------------------------|------------------------------|
| **Higher (e.g., 30s)** | Increases total scan duration; slow services get more time to respond | Reduces false negatives from prematurely abandoned requests |
| **Lower (e.g., 2–5s)** | Shortens scan dramatically by cutting off slow responses early | Risks missing valid accounts on sluggish or throttled services |
| **Default (10s)** | Balanced for typical public internet conditions | Reasonable fallback when modules don't specify their own timeout |

Because the client is shared and reused, the timeout governs **all network I/O** performed during the scan. A single hung endpoint cannot block the entire run due to Holehe's exception handling: when `httpx` raises a `TimeoutException`, the module catches it via generic `except Exception` handlers and records the site as *not found* rather than propagating the error.

## Reliability Considerations for Timeout Tuning

Three environmental factors should guide your timeout selection:

1. **Network variability** — Transient latency spikes on consumer internet connections can trigger premature timeouts; a more generous setting accommodates these fluctuations.

2. **Service rate‑limiting** — Some platforms deliberately slow responses to throttled connections; shorter timeouts may cause repeated failures before any retry logic engages.

3. **Resource consumption** — Longer timeouts keep TCP connections and associated file descriptors open longer, increasing memory pressure during large‑scale scans.

The timeout parameter thus serves as a **reliability dial**: lower values prioritize speed and resource efficiency at the cost of completeness, while higher values maximize detection coverage for slower or more constrained target environments.

## Practical Usage Examples

Run Holehe with CLI flags to adjust timeout behavior:

```bash

# Default 10-second timeout (no flag required)

holehe -e target@example.com

# Increase to 30 seconds for unreliable networks

holehe -e target@example.com -T 30

# Aggressive 5-second scan for quick reconnaissance

holehe -e target@example.com -T 5

```

When using Holehe programmatically, you replicate the same pattern:

```python
import httpx

# Create client with custom global timeout

client = httpx.AsyncClient(timeout=20)

# Module uses global timeout

await client.get("https://fast-service.com")

# Module overrides for specific request

await client.get("https://slow-service.com", timeout=3)

```

## Summary

- The `--timeout` flag sets a **global default** for all HTTP requests in Holehe, parsed in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) and applied to the shared `httpx.AsyncClient`.
- Modules can **override per‑request** with hardcoded values when they anticipate faster or slower services.
- Higher timeouts improve **detection accuracy** by reducing false negatives; lower timeouts improve **scan speed** and reduce resource usage.
- Timeout exceptions are **isolated per module**, preventing a single slow service from crashing the entire scan.
- Tailor your timeout setting based on **network stability**, **target service behavior**, and your tolerance for incomplete results.

## Frequently Asked Questions

### What happens if a request exceeds the timeout in Holehe?

`httpx` raises a `TimeoutException`, which the module catches and handles by marking that specific site as not found. The scan continues with remaining modules unaffected.

### Can individual modules have different timeouts than the global setting?

Yes. Modules specify per‑request timeouts directly in their `client.get()` or `client.post()` calls, overriding the global client value for that single request. Examples include [`myspace.py`](https://github.com/megadose/holehe/blob/main/myspace.py) (2s), [`caringbridge.py`](https://github.com/megadose/holehe/blob/main/caringbridge.py) (3s), and several forum modules (1s).

### Does increasing the timeout always improve accuracy?

Not necessarily. While longer timeouts reduce false negatives from slow responses, they also prolong scans and increase resource consumption. On stable, fast networks, the default 10 seconds or lower often suffices without significant accuracy loss.

### How do I choose the right timeout for my environment?

Start with the default 10 seconds. If you observe many timeout errors or suspect missed accounts on slower services, increase to 20–30 seconds. For quick, high‑volume scans on reliable networks, try 5 seconds and verify whether critical services are being skipped.