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

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, 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 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

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

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:

holehe example@example.com

Set a custom timeout of 5 seconds:

holehe example@example.com --timeout 5

Use the short flag variant for brevity:

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 while overriding the default parameters.

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.
• 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, 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. 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 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, this single client instance (initialized at lines 208-213) handles all concurrent requests, meaning every service query shares the identical timeout limit you specified.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}