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

> Discover how Sherlock's timeout configuration works, its default 60-second value, and how to customize it using the CLI or Python API for efficient HTTP requests.

- Repository: [Sherlock/sherlock](https://github.com/sherlock-project/sherlock)
- Tags: internals
- Published: 2026-03-02

---

**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`](https://github.com/sherlock-project/sherlock/blob/main/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`](https://github.com/sherlock-project/sherlock/blob/main/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`](https://github.com/sherlock-project/sherlock/blob/main/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:

```bash

# 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:

```python
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`](https://github.com/sherlock-project/sherlock/blob/main/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`](https://github.com/sherlock-project/sherlock/blob/main/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`](https://github.com/sherlock-project/sherlock/blob/main/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`](https://github.com/sherlock-project/sherlock/blob/main/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.