How Sherlock's Timeout Configuration Works: Default Values and Customization

Sherlock's timeout configuration defaults to 60 seconds and can be customized via the --timeout CLI flag or the timeout parameter in the Python API, with all values validated through the timeout_check() function before being passed to underlying HTTP requests.

The timeout configuration in the sherlock-project/sherlock repository controls how long the tool waits for HTTP responses when querying social media platforms. Understanding how this mechanism works—and its default value—is essential for optimizing scan performance across networks with varying latency.

How Timeout Configuration Works in Sherlock

The timeout system operates through a validated pipeline that ensures every network request adheres to user-defined or default limits before hitting the wire.

CLI Argument Parsing and Validation

In sherlock_project/sherlock.py (lines 618–626), the CLI defines the --timeout flag using type=timeout_check to enforce valid inputs. The timeout_check() function (lines 505–527) converts string inputs to float, rejects non-positive values, and returns the numeric timeout for downstream use.

Core Function Signature and Defaults

The sherlock() function signature in sherlock_project/sherlock.py (lines 170–190) declares timeout: int = 60, establishing the default timeout of 60 seconds. This default mirrors the CLI configuration, ensuring consistency whether using the command line or importing the Python module directly.

HTTP Request Propagation

Once validated, the timeout value propagates to every HTTP request in sherlock_project/sherlock.py (around lines 320–328). The value is passed directly to requests.get(..., timeout=timeout) and the async SherlockFuturesSession, ensuring requests abort if servers fail to respond within the specified period.

Default Timeout Value

Sherlock sets the default timeout to 60 seconds across all interfaces. This value balances thoroughness with practicality, allowing adequate time for slower responding servers while preventing indefinite hangs. When a request exceeds this limit, the underlying requests library raises a Timeout exception, which Sherlock captures and logs as an error for that specific site query.

Customizing Timeout Settings

Users can override the 60-second default through both command-line arguments and programmatic API calls.

Command Line Usage

To specify a custom timeout via CLI:

# Use default 60 seconds

sherlock username

# Set explicit 20-second timeout

sherlock --timeout 20 username

Python API Integration

When calling Sherlock programmatically, pass the timeout parameter directly to the sherlock() function:

from sherlock_project.sherlock import sherlock

# Execute with custom 10-second timeout

results = sherlock(
    username="targetUser",
    site_data=site_data,
    query_notify=notify_object,
    timeout=10  # Overrides default 60s

)

Summary

• Sherlock's timeout configuration defaults to 60 seconds for all HTTP requests.
• The timeout_check() function in sherlock_project/sherlock.py (lines 505–527) validates that all inputs are positive numbers before conversion to float.
• CLI users customize timeouts via the --timeout flag defined in lines 618–626 of sherlock_project/sherlock.py.
• The core sherlock() function accepts a timeout parameter (defaulting to 60) in its signature at lines 170–190.
• Exceeded timeouts trigger requests library exceptions, which Sherlock handles as query errors for individual sites.

Frequently Asked Questions

What is the default timeout value in Sherlock?

The default timeout value is 60 seconds. This is hardcoded in the sherlock() function signature in sherlock_project/sherlock.py (lines 170–190) as timeout: int = 60, and matches the CLI default defined in the argument parser.

How does Sherlock validate timeout values?

Sherlock validates timeout values through the timeout_check() function located in sherlock_project/sherlock.py (lines 505–527). This function converts string inputs to float, rejects any non-positive numbers, and ensures only valid numeric timeouts reach the HTTP request layer.

Can I set different timeouts for different websites?

No, the current implementation in sherlock-project/sherlock applies a single global timeout value to all HTTP requests during a scan. The timeout parameter in the sherlock() function and the --timeout CLI argument set one value that propagates to every site query through the requests.get(..., timeout=timeout) calls.

What happens when a request exceeds the timeout limit?

When a request exceeds the configured timeout, the Python requests library raises a Timeout exception. Sherlock catches this exception during execution and records it as an error status for that specific website query, allowing the scan to continue with remaining targets rather than hanging indefinitely.

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