# How to Set a Custom Timeout for Requests in Holehe

> Easily set a custom timeout for requests in Holehe using the -T flag. Learn how to control request duration and optimize your experience with this simple guide.

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

---

**Use the `-T` or `--timeout` command-line flag to specify a custom timeout in seconds when running Holehe; the default is 10 seconds.**

Holehe is an open-source OSINT tool that checks email addresses across hundreds of services using asynchronous HTTP requests. If you need to know how to set a custom timeout for requests in Holehe, the tool provides a straightforward CLI option that controls the global timeout for all **httpx**-based requests. Here's how it works under the hood and how to use it effectively.

---

## Where Timeout Configuration Lives in the Source Code

The timeout handling is implemented in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py), which contains both the argument parsing and client instantiation logic.

### CLI Argument Definition

Lines 194–196 define the `-T/--timeout` argument:

```python
parser.add_argument("-T","--timeout", type=int , default=10,
                    required=False,dest="timeout",
                    help="Set max timeout value (default 10)")

```

This sets the **default timeout to 10 seconds** and accepts any integer value you specify.

### Client Instantiation with Timeout

The parsed value is applied when creating the `httpx.AsyncClient` at line 213:

```python
client = httpx.AsyncClient(timeout=timeout)

```

Because Holehe uses this single client instance across all service modules, your timeout setting propagates globally to every request.

---

## Setting Timeout via Command Line

### Basic Usage with Custom Timeout

Run Holehe with a 30-second timeout:

```bash
holehe -T 30 user@example.com

```

Or use the long-form option:

```bash
holehe --timeout 30 user@example.com

```

### Using the Default Timeout

Omit the flag to use the 10-second default:

```bash
holehe user@example.com

```

---

## Programmatic Timeout Configuration

If you're importing Holehe's functionality into your own Python code, you can create a custom `httpx.AsyncClient` with your desired timeout:

```python
import httpx
from holehe.core import maincore

# Create client with 20-second timeout

client = httpx.AsyncClient(timeout=20)

# Use with Holehe's internal functions

# (adapt based on your specific integration needs)

```

Note that direct programmatic usage requires understanding Holehe's internal API, as the primary interface is CLI-based.

---

## When to Adjust Your Timeout

| Scenario | Recommended Timeout | Rationale |
|----------|-------------------|-----------|
| Fast, stable connections | 5–10 seconds | Default works well; minimizes wait time |
| Slow or unstable networks | 30–60 seconds | Prevents false negatives from timing out |
| Rate-limited services | 15–30 seconds | Allows for delayed responses without hanging indefinitely |
| Debugging or development | Higher values | Identifies if services are slow versus completely unavailable |

---

## Per-Module Timeout Overrides

While the global timeout covers most use cases, individual modules in `holehe/modules/` can theoretically override timeouts in their specific request calls. For example, examining [`holehe/modules/social_media/myspace.py`](https://github.com/megadose/holehe/blob/main/holehe/modules/social_media/myspace.py) shows how per-request timeout parameters could be passed, though most modules rely on the shared client configuration. Modifying individual modules is generally discouraged unless you have a specific reason to break from the global setting.

---

## Summary

- **The `-T/--timeout` flag** is the standard way to set a custom timeout for requests in Holehe
- **Default timeout is 10 seconds**, defined in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) lines 194–196
- **Global application**: the timeout applies to all service checks via a shared `httpx.AsyncClient`
- **Adjust based on network conditions**: slower connections need higher values to avoid missing valid results
- **Source file**: [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) handles both argument parsing and client creation

---

## Frequently Asked Questions

### What is the default timeout in Holehe?

The default timeout is **10 seconds**, hard-coded in the argument parser at [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) line 195. This means any HTTP request that doesn't complete within 10 seconds will be aborted and the service check will fail.

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

Not through the CLI. Holehe uses a single `httpx.AsyncClient` instance with a uniform timeout. To use different timeouts per service, you would need to modify individual module files in `holehe/modules/` to pass custom timeout values to specific `client.get()` or `client.post()` calls.

### Does the timeout include connection time and response time?

Yes. The timeout value you pass to `-T/--timeout` becomes the **total timeout** for each HTTP request, covering both establishing the connection and receiving the complete response. This is standard httpx behavior as configured in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) at line 213.

### What happens if a request times out?

When a request exceeds the timeout limit, Holehe marks that service check as failed and moves to the next target. The timeout failure is typically recorded in the output, allowing you to identify which services couldn't be reached within your specified timeframe.