# How to Configure Custom HTTP Timeouts with the `--timeout` Argument in holehe

> Configure custom HTTP timeouts in holehe using the --timeout argument. Override the default 10-second timeout for faster OSINT reconnaissance. Learn how now.

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

---

**Pass `--timeout <seconds>` to override the 10-second default for all HTTP requests made during OSINT reconnaissance.**

holehe is an open-source OSINT tool for email reconnaissance that checks hundreds of websites for account existence. When scanning large target lists or operating on unstable networks, controlling HTTP timeout behavior becomes critical for reliable results. The `--timeout` argument, implemented in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py), lets you adjust how long the tool waits for each remote server response.

## How the `--timeout` Argument Works in holehe

The timeout configuration flows through two core components: the command-line interface parser and the HTTP request helper.

### CLI Argument Definition in core.py

In [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py), the argument parser defines the `--timeout` option with a default value of 10 seconds:

```python

# From holehe/core.py

parser.add_argument(
    "-T", "--timeout",
    type=int,
    default=10,
    required=False,
    dest="timeout",
    help="HTTP request timeout in seconds (default: 10)",
)

```

The `type=int` enforcement ensures only integer values are accepted. The `-T` short form provides a quick alternative for frequent use.

### Timeout Propagation to HTTP Requests

After parsing, `args.timeout` passes through to the request instrumentation in [`holehe/instruments.py`](https://github.com/megadose/holehe/blob/main/holehe/instruments.py). The request helper forwards this value directly to Python's `requests` library:

```python

# Simplified from holehe/instruments.py

def request(url, timeout, **kwargs):
    return requests.get(url, timeout=timeout, **kwargs)

```

This design means **every HTTP request** made by holehe modules uses your specified timeout consistently.

## Practical Usage Examples

### Basic Timeout Override

Increase timeout for slow residential connections:

```bash
holehe -u target@example.com --timeout 30

```

### Aggressive Fast Scanning

Reduce timeout for rapid reconnaissance on responsive networks:

```bash
holehe -u target@example.com --timeout 5

```

### Using the Short Form

```bash
holehe -u target@example.com -T 15

```

## Timeout Behavior and Error Handling

When a request exceeds the configured timeout, holehe raises `requests.exceptions.Timeout`. The tool catches these exceptions per-module and continues scanning remaining services rather than failing entirely.

According to the holehe source code, modules handle timeout exceptions gracefully:

- The specific service check returns `None` or error status
- Execution proceeds to the next target module
- Final output indicates which checks timed out

This design ensures **partial results are preserved** even when some services are unresponsive.

## Performance Considerations

| Timeout Value | Use Case | Trade-off |
|-------------|----------|-----------|
| 3-5 seconds | Fast scanning, reliable networks | Higher false-negative rate for slow services |
| 10 seconds (default) | Balanced operation | Standard reliability |
| 30-60 seconds | Slow VPNs, Tor, high-latency targets | Much slower overall scan time |

Increasing timeout linearly impacts total scan duration. With 300+ services checked, a 60-second timeout creates a worst-case 5-minute delay per email address.

## Summary

- holehe uses `--timeout` with a **10-second default**, defined in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py)
- Values pass through [`holehe/instruments.py`](https://github.com/megadose/holehe/blob/main/holehe/instruments.py) to Python's `requests` library
- Accepts integer seconds via `-T` short form or `--timeout` long form
- Timeouts are **per-request**, not per-email or per-scan
- Failed timeouts skip individual modules without crashing the full scan

## Frequently Asked Questions

### What happens if I don't specify a timeout?

holehe defaults to **10 seconds** per HTTP request. This value is hardcoded in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) as `default=10` in the argument parser definition.

### Can I set different timeouts for different services?

No. The holehe architecture uses a **global timeout value** passed to all request calls through [`holehe/instruments.py`](https://github.com/megadose/holehe/blob/main/holehe/instruments.py). Per-service timeout configuration would require modifying individual module files.

### Why does my scan hang even with a short timeout?

Some modules may use separate connection pools or DNS resolution that isn't covered by the requests timeout. The `--timeout` parameter specifically controls the `requests.get`/`requests.post` timeout parameter, not underlying TCP connection establishment in all edge cases.

### Does timeout affect rate limiting or retry behavior?

No. The timeout parameter only controls **single request duration**. holehe does not implement automatic retries; each service check makes one attempt with your specified timeout, then proceeds.