# How to Set a Custom HTTP Timeout for Holehe: CLI Configuration Guide

> Learn how to set a custom HTTP timeout for Holehe with the CLI using the --timeout flag. Easily control request durations for your security checks.

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

---

**Use the `--timeout` or `-T` flag followed by the duration in seconds (e.g., `--timeout 30`) to override the default 10-second HTTP request timeout when running holehe from the command line.**

The `megadose/holehe` email reconnaissance framework provides configurable HTTP timeout settings to accommodate varying network conditions and target response times. Setting a custom HTTP timeout for Holehe prevents premature termination of OSINT modules when investigating slow or rate-limited services. This configuration is implemented through Python's `argparse` module in the core CLI and propagates through the request handling stack to the underlying HTTP client.

## Configuring the `--timeout` Argument in holehe/core.py

The command-line interface definition in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) exposes timeout control via the `-T`/`--timeout` argument. This parameter accepts an integer value representing the maximum seconds to wait for server responses before raising a timeout exception.

The argument is registered in theArgumentParser instance as follows:

```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)",
)

```

When parsing completes, the value is stored in `args.timeout` and passed throughout the application lifecycle.

## Practical Command Line Examples

You can specify custom timeout values using either the long or short flag format. The default value of **10 seconds** applies when the flag is omitted.

Set a 30-second timeout for slow networks or Tor connections:

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

```

Use the short flag for aggressive scanning with reduced wait times:

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

```

Run with the library default for standard broadband connections:

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

```

## Timeout Propagation Through the Codebase

The timeout value flows from CLI parsing to HTTP execution through two primary source files.

### Argument Parsing in core.py

After parsing, `args.timeout` contains the integer value specified by the user (or the default 10). This value is forwarded to the asynchronous execution context and eventually reaches the network layer.

```python

# Simplified flow in holehe/core.py

args = parser.parse_args()

# args.timeout now contains the configured value (int)

# This value is passed to the module execution context

```

### HTTP Request Execution in instruments.py

The actual HTTP request implementation resides in [`holehe/instruments.py`](https://github.com/megadose/holehe/blob/main/holehe/instruments.py). The `request` helper function receives the timeout parameter and passes it directly to Python's `requests` library.

```python

# From holehe/instruments.py

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

```

This ensures that every HTTP request made by holehe modules respects the user-defined timeout threshold.

## Best Practices for Timeout Configuration

Adjust timeout values based on your specific operational environment:

- **Increase to 30-60 seconds** when operating over Tor, VPNs, or high-latency networks to prevent false negatives from slow routing.
- **Decrease to 3-5 seconds** for aggressive scanning on fast, stable connections where you prioritize speed over comprehensive coverage.
- **Maintain default 10 seconds** for standard broadband investigations where target services typically respond within standard HTTP timeframes.

## Summary

- The `--timeout` argument in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) accepts integer values representing seconds.
- The default HTTP timeout is **10 seconds** when no flag is provided.
- Configuration values propagate from the CLI parser to [`holehe/instruments.py`](https://github.com/megadose/holehe/blob/main/holehe/instruments.py) and the underlying `requests` library.
- Use `-T` as a shorthand alias for `--timeout` in command line operations.

## Frequently Asked Questions

### What is the default HTTP timeout in Holehe?

The default timeout is **10 seconds**, hardcoded in the `argparse` configuration within [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py). This value applies to all HTTP requests unless overridden via command line arguments.

### How do I increase the timeout for slow connections?

Append `--timeout 30` (or higher) to your holehe command. This is particularly useful when routing traffic through Tor or investigating geographically distant servers that exhibit high latency.

### Where is the timeout parameter processed in the source code?

The value is initially parsed in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) by the ArgumentParser, then passed to the request helper function in [`holehe/instruments.py`](https://github.com/megadose/holehe/blob/main/holehe/instruments.py), which forwards the parameter to `requests.get()` or `requests.post()` calls.

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

No. The `--timeout` flag sets a global value that applies uniformly to all HTTP requests made during a single holehe execution. For varying timeout requirements per target, you must run separate holehe instances with different timeout configurations.