# How to Set a Custom HTTP Timeout for Requests in Holehe

> Learn how to set a custom HTTP timeout in Holehe using the --timeout or -T argument. Optimize your request speed and prevent hangs by specifying your desired timeout in seconds.

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

---

**TLDR:** You can configure a custom HTTP timeout in Holehe by passing the `--timeout` argument (or `-T`) followed by the number of seconds; this value is parsed in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) and applied to all outgoing requests via the `timeout` parameter in [`holehe/instruments.py`](https://github.com/megadose/holehe/blob/main/holehe/instruments.py), with a default of 10 seconds.

Holehe, the open-source email OSINT tool by megadose, checks email address registration status across hundreds of websites using asynchronous HTTP requests. When network latency varies or target services respond slowly, adjusting the **custom HTTP timeout** prevents premature failures and ensures complete scans. The timeout configuration is implemented through Python's **argparse** module in the core CLI handler and enforced uniformly across all verification modules.

## Locating the Timeout Configuration in holehe/core.py

The command-line interface defines the timeout parameter using **argparse** in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py). The tool registers a `-T`/`--timeout` option that accepts integer values, defaulting to **10 seconds** when unspecified.

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

```

After parsing command-line input, the value is stored in the `args.timeout` attribute. This variable is subsequently passed to the asynchronous request handlers that orchestrate module execution.

## How holehe/instruments.py Applies the Timeout

The actual HTTP request implementation resides in [`holehe/instruments.py`](https://github.com/megadose/holehe/blob/main/holehe/instruments.py), which wraps Python's **requests** library. The helper functions receive the timeout value from the core module and inject it directly into every `requests.get` or `requests.post` call, ensuring consistent network behavior across all OSINT checks.

```python

# Simplified from holehe/instruments.py

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

```

This architecture ensures that modifying the CLI argument propagates immediately to every website check without requiring changes to individual module code.

## Practical Examples for Using Custom Timeouts

You can adjust the timeout based on your network conditions and target reliability.

- **Default behavior (10 seconds):**
  
  ```bash
  holehe -u test@example.com
  ```

- **Extended timeout for slow networks (30 seconds):**
  
  ```bash
  holehe -u test@example.com --timeout 30
  ```

- **Aggressive fast scanning (5 seconds):**
  
  ```bash
  holehe -u test@example.com -T 5
  ```

Setting a higher value is recommended when scanning through VPNs or Tor connections where latency fluctuates, while lower values accelerate scans against well-known, responsive APIs.

## Summary

- Holehe accepts a **custom HTTP timeout** via the `-T` or `--timeout` CLI argument defined in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py).
- The default timeout is **10 seconds**, suitable for standard broadband connections.
- The integer value is parsed by **argparse** and stored in `args.timeout`.
- [`holehe/instruments.py`](https://github.com/megadose/holehe/blob/main/holehe/instruments.py) applies this value to all `requests` library calls, ensuring uniform timeout behavior across every email verification module.
- Adjust this parameter when experiencing false negatives due to network latency or when optimizing scan duration.

## Frequently Asked Questions

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

The default timeout is **10 seconds**, as defined by the `default=10` parameter in the argparse configuration within [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py). If you do not specify `--timeout`, every HTTP request will wait up to 10 seconds for a response before raising a timeout exception.

### Can I set different timeouts for different verification modules?

No, the current implementation in megadose/holehe uses a global timeout value passed from `args.timeout` to the centralized request handler in [`holehe/instruments.py`](https://github.com/megadose/holehe/blob/main/holehe/instruments.py). All modules share the same timeout duration for consistency; you cannot configure per-module timeouts without modifying the source code.

### Why does Holehe hang even when I set a high timeout value?

If the tool appears to hang despite a high **custom HTTP timeout**, the issue likely stems from connection-level timeouts outside the scope of the requests library's `timeout` parameter, such as DNS resolution delays or TCP connection timeouts at the operating system level. Ensure your system-level resolver settings are configured appropriately, or investigate potential proxy misconfigurations.

### Is there a maximum limit for the timeout value?

There is no enforced upper limit in the Holehe source code; you can specify any positive integer accepted by Python's **requests** library (e.g., `--timeout 300` for 5 minutes). However, excessively high values may cause the tool to run indefinitely if a target server never responds, so use practical limits based on your scanning requirements.