# How to Set the HTTP Timeout for Holehe: CLI and Programmatic Guide

> Learn how to set the HTTP timeout for Holehe using the -T or --timeout flag. Configure network request timeouts in seconds for CLI and programmatic use.

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

---

**To set the HTTP timeout for Holehe, use the `-T` or `--timeout` flag followed by the number of seconds (default is 10), which configures the underlying httpx.AsyncClient used for all network requests.**

Holehe is an email OSINT tool that checks for account registrations across hundreds of platforms using asynchronous HTTP requests. Since the tool relies on the **httpx** library for all network communication, controlling the maximum wait time for responses is essential for reliable scanning across slow networks. Knowing how to set the HTTP timeout for Holehe prevents indefinite hangs while ensuring comprehensive coverage.

## Command-Line Method to Set the HTTP Timeout for Holehe

The simplest way to configure request timeouts is through the command-line interface. The tool accepts a `-T` or `--timeout` argument that accepts an integer representing the maximum number of seconds to wait for a response.

When you omit the flag, Holehe defaults to **10 seconds** for all HTTP requests.

### CLI Usage Examples

```bash

# Run with default 10-second timeout

holehe -l email@example.com

# Set a custom 20-second timeout

holehe -T 20 -l email@example.com

# Alternative long-form flag

holehe --timeout 30 -l email@example.com

```

## How Timeout Configuration Works in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py)

According to the Holehe source code, the timeout value propagates from CLI arguments directly to the HTTP client initialization. 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, stores the parsed value in `args.timeout`, and passes this to the `httpx.AsyncClient` constructor.

The relevant implementation creates the global client instance as follows:

```python
import httpx
import argparse

parser = argparse.ArgumentParser()
parser.add_argument("-T", "--timeout", type=int, default=10,
                    help="Set max timeout value (default 10)")
args = parser.parse_args()

# Global client initialization with configured timeout

client = httpx.AsyncAsyncClient(timeout=args.timeout)

```

This configuration applies globally to all requests made by Holehe during execution.

## Global vs. Module-Specific Timeouts

While the global timeout applies to most operations, individual modules sometimes set their own timeout values for specific platform checks. For example, certain forum modules may specify shorter timeouts directly in their request calls.

However, the global `httpx.AsyncClient` timeout acts as the default for all requests that do not explicitly override the parameter. In [`holehe/modules/forum/onlinesequencer.py`](https://github.com/megadose/holehe/blob/main/holehe/modules/forum/onlinesequencer.py), you can observe modules passing specific timeout arguments to individual requests, though these are exceptions rather than the standard behavior.

If you encounter inconsistent timeout behavior, check whether the specific module hardcodes its own value, as this would bypass your global CLI setting.

## Programmatic Usage Within Holehe

If you are extending Holehe or integrating its functionality into custom scripts, maintain the same pattern used in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py):

```python
import httpx

# Configure your desired timeout

timeout_seconds = 20

# Initialize client consistent with Holehe's implementation

client = httpx.AsyncClient(timeout=timeout_seconds)

# Execute requests (timeout applies automatically)

response = await client.get("https://target-platform.com")

```

## Summary

- Set the HTTP timeout for Holehe using the `-T` or `--timeout` CLI flag followed by seconds (e.g., `-T 20`).
- The default timeout is **10 seconds** when no flag is provided.
- Configuration is handled in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py), where `args.timeout` initializes the `httpx.AsyncClient`.
- The timeout applies globally to all requests unless individual modules explicitly override it with hardcoded values.
- Holehe uses **httpx** rather than synchronous libraries to support concurrent asynchronous requests.

## Frequently Asked Questions

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

The default timeout is **10 seconds**. This value is defined in the argument parser within [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) and applies to all HTTP requests made by the `httpx.AsyncClient` unless you specify a different value using the `--timeout` or `-T` flag.

### Can I set different timeouts for different websites when using Holehe?

No, the CLI provides a single global timeout value that configures the entire `httpx.AsyncClient` instance. While some individual modules (such as those in `holehe/modules/forum/`) may implement their own timeout logic for specific requests, you cannot configure per-site timeouts through the standard command-line interface.

### Why does Holehe use httpx instead of the standard requests library?

Holehe uses **httpx** because it supports **asynchronous HTTP requests**, allowing the tool to check hundreds of platforms concurrently for significantly better performance. The timeout parameter in httpx follows similar semantics to requests but integrates with Python's asyncio ecosystem used throughout Holehe's architecture.

### What happens if a request exceeds the specified timeout?

If a request exceeds the timeout value (whether the default 10 seconds or your custom setting), httpx raises a `TimeoutException`. Holehe catches this and marks that specific platform check as failed or unavailable, continuing execution against the remaining target sites without terminating the entire scan.