# How to Set a Custom Timeout for Holehe Checks: CLI and Source Guide

> Learn how to set a custom timeout for Holehe checks using the CLI -T flag. Configure the internal httpx.AsyncClient timeout for faster or slower scans. Guide for megadose/holehe.

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

---

**To set a custom timeout for Holehe checks, use the `-T` or `--timeout` command-line flag followed by the desired number of seconds, which configures the internal `httpx.AsyncClient` timeout value.**

Holehe, an open-source OSINT tool developed by **megadose/holehe** for checking email and username availability across hundreds of platforms, relies on asynchronous HTTP requests to query various services. When you need to set a custom timeout for holehe checks to accommodate slow network conditions or strict performance requirements, the tool provides a built-in command-line interface to override the default limit.

## Understanding the Timeout Architecture in Holehe

The timeout mechanism in Holehe follows a direct path from user input to network execution. According to the megadose/holehe source code, the application uses Python's **argparse** module to capture user preferences in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py), then passes this value immediately to an **httpx.AsyncClient** instance. This design ensures that every asynchronous HTTP request made during the email checking process adheres to the same timeout threshold, preventing indefinite hangs on unresponsive services.

## Where the Timeout is Defined in the Source Code

### Command-Line Argument Parsing

In [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) at line 194, the argument parser defines the timeout option with a default value of **10 seconds**. The implementation adds a `-T` shortcut alongside the `--timeout` flag, allowing users to specify the maximum wait time for each network request.

*Source reference:* [`holehe/core.py#L194`](https://github.com/megadose/holehe/blob/master/holehe/core.py#L194)

### HTTP Client Configuration

Immediately following argument parsing, between lines 208 and 213 in the same file, Holehe instantiates the HTTP client using the parsed timeout value. The code creates an `httpx.AsyncClient(timeout=timeout)` object, ensuring that all subsequent requests to social media platforms respect the user-defined limit.

*Source reference:* [`holehe/core.py#L208-L213`](https://github.com/megadose/holehe/blob/master/holehe/core.py#L208-L213)

## Step-by-Step: Setting a Custom Timeout for Holehe Checks

To adjust the timeout duration when running Holehe from the terminal, append the timeout flag followed by the desired duration in seconds.

Run with the default 10-second timeout:

```bash
holehe example@example.com

```

Set a custom timeout of 5 seconds:

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

```

Use the short flag variant for brevity:

```bash
holehe example@example.com -T 3

```

## Programmatic Timeout Configuration

If integrating Holehe into a Python script rather than using the CLI, you can simulate command-line arguments to set the timeout programmatically. This approach leverages the same `main` function defined in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) while overriding the default parameters.

```python
import sys
from holehe.core import main

# Configure arguments with custom timeout

sys.argv = ["holehe", "target@email.com", "--timeout", "15"]
main()

```

This method directly manipulates the argument vector before the parser at line 194 processes the configuration, ensuring the `httpx.AsyncClient` receives your custom timeout value.

## Summary

- Holehe uses the `-T` or `--timeout` flag to set a custom timeout for holehe checks, overriding the default 10-second value defined in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py).
- The argument is parsed at line 194 using Python's **argparse** module, where the default is hardcoded as 10 seconds.
- The timeout value is applied to an `httpx.AsyncClient` instance at lines 208-213 in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py), governing all asynchronous HTTP requests.
- A single global timeout applies to every service check; there is no per-platform timeout configuration in the current architecture.
- Programmatic usage requires manipulating `sys.argv` before invoking the main function to pass timeout values.

## Frequently Asked Questions

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

The default timeout is **10 seconds**, as defined in the argparse configuration at line 194 of [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py). If you do not specify the `-T` or `--timeout` flag, the tool will wait up to 10 seconds for each service to respond before marking the check as failed and moving to the next platform.

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

Currently, Holehe applies a single global timeout value to all HTTP requests through the centralized `httpx.AsyncClient` configuration. The source code in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) does not implement per-service timeout routing; the value you provide via `--timeout` applies uniformly to every platform being checked during that execution.

### What happens when a Holehe check times out?

When a request exceeds the specified timeout duration, the `httpx` library raises a timeout exception that Holehe catches and handles gracefully. The tool records this as a failed or inconclusive check for that specific service and continues processing the remaining platforms in the query list without terminating the entire scan.

### Does the timeout flag affect all HTTP requests equally?

Yes, the timeout value passed via `-T` or `--timeout` configures the underlying `httpx.AsyncClient` instance used throughout the entire checking process. According to the implementation in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py), this single client instance (initialized at lines 208-213) handles all concurrent requests, meaning every service query shares the identical timeout limit you specified.