Sherlock is a Python-based command-line tool designed for OSINT practitioners and security researchers who need to quickly find where a given username exists across a vast array of social networks. It tackles a common reconnaissance problem — mapping a target’s online presence from a single username — by scanning over 400 platforms with a consistent, extensible architecture.
How Sherlock detects usernames across hundreds of social networks
At its core, Sherlock uses a JSON-driven architecture to define its knowledge about each supported social network. This data.json file contains metadata and detection rules for 400+ sites, specifying how to construct user profile URLs and how to interpret HTTP responses to confirm account existence.
For each social network, Sherlock defines:
- The URL pattern to check a username’s profile page.
- Expected HTTP status codes indicating the presence or absence of the user.
- Optional content patterns (strings or regex) to verify the page’s content and reduce false positives.
- Redirect behaviors that might signal account existence or nonexistence.
The tool sends HTTP requests to these URLs and analyzes the response based on the above rules. For example, a 200 status with certain content patterns might indicate the username exists, while a 404 or redirect to a generic “user not found” page suggests otherwise.
This data-driven approach separates the detection logic from the code, allowing the community and maintainers to update site rules easily when social networks change their layouts or policies. It also keeps the Python codebase clean and focused on request handling, concurrency, result aggregation, and output formatting.
Sherlock supports both single username checks and batch scans, making it flexible for different investigation scales. It outputs results in plain text, CSV, or XLSX, catering to manual review or automated pipelines.
The codebase is pure Python, relying on standard libraries and popular HTTP clients. It supports proxy usage and custom timeouts, essential for large-scale or privacy-conscious reconnaissance. This flexibility is crucial for working around rate limits or network restrictions.
The data-driven detection system: balancing extensibility and accuracy
What sets Sherlock apart is its modular, JSON-based site detection mechanism. Instead of hardcoding scraping logic for each social network, it treats site definitions as data. This has several benefits:
- Extensibility: Adding or modifying sites only requires updating the JSON file, not the Python code.
- Maintainability: The detection logic is consistent across sites, reducing bugs and simplifying testing.
- Community-driven: Users can contribute new site definitions or fixes without deep Python knowledge.
The tradeoff is that this method heavily depends on HTTP status codes and shallow content checks, which can produce false positives or negatives if a site changes unexpectedly. Sherlock mitigates this by allowing regex or string checks in page content to confirm results, but it’s never foolproof.
The code is surprisingly clean for a project of this size, with clear separation between the network logic, result handling, and CLI interface. The use of JSON also means the tool can be extended or integrated into other Python applications with minimal effort.
However, because it’s a CLI tool primarily focused on reconnaissance, it doesn’t attempt deep scraping or login-required checks. This limitation is inherent to the problem space — you either get fast, broad scans or slow, deep digs.
Installation and quickstart
Sherlock offers multiple installation and usage options, making it accessible for different user preferences and environments. From the README:
## Installation
> [!WARNING]
> Packages for ParrotOS and Ubuntu 24.04, maintained by a third party, appear to be __broken__.
> Users of these systems should defer to `uv`/`pipx`/`pip` or Docker.
| Method | Notes |
| - | - |
| `pipx install sherlock-project` | `pip` or `uv` may be used in place of `pipx` |
| `docker run -it --rm sherlock/sherlock` |
| `dnf install sherlock-project` | |
Community-maintained packages are available for Debian (>= 13), Ubuntu (>= 22.10), Homebrew, Kali, and BlackArch. These packages are not directly supported or maintained by the Sherlock Project.
See all alternative installation methods here.
Once installed, you can run a simple username check:
sherlock username
For batch scanning, create a file with usernames and run:
sherlock -f usernames.txt
The tool supports output flags to save results in CSV or XLSX formats and options for proxy configuration, timeout adjustments, and loading custom site definitions.
Who should use Sherlock and when
Sherlock is ideal for security researchers, OSINT analysts, and anyone needing a quick map of a username’s social footprint across a broad range of platforms. Its data-driven design means it’s easy to keep current as social networks evolve, and its Python codebase encourages integration or extension.
The main limitation is its reliance on HTTP status and content pattern matching, which can lead to false positives or missed accounts if sites change or employ anti-scraping measures. It also doesn’t handle authenticated or private data.
For many reconnaissance tasks, this tradeoff of breadth over depth is acceptable — Sherlock provides a fast, modular, and user-friendly baseline for username enumeration.
If you need faster or deeper crawling, or integration with APIs where available, you’ll want to complement Sherlock with other tools. But as a starting point or lightweight solution, it remains one of the most accessible and widely used OSINT username scanners.
Overall, Sherlock’s architecture and community-driven site database make it a solid example of practical, extensible reconnaissance tooling in Python.
Related Articles
- Maigret: A resilient OSINT username scraper across thousands of sites — Maigret is a Python-based OSINT tool that scrapes public profiles by username from 3,000+ sites without API keys. It fea
- Social-Media-OSINT: a curated toolkit for social media investigations — Social-Media-OSINT is a curated collection of 200+ tools for social media intelligence gathering, organized by platform
- ForensiX: ML-powered forensic analysis of Chrome and Brave browser artifacts — ForensiX combines ML-driven URL classification with browser artifact extraction for forensic analysis of Chrome and Brav
- HoundDog.ai: deterministic static analysis for privacy-focused dataflow tracking — HoundDog.ai scans large codebases locally to detect sensitive data leaks using deterministic static analysis combined wi
- Inside X’s recommendation engine: multi-stage candidate sourcing and neural ranking — Explore the architecture behind X’s For You Timeline recommendation system, built on Scala, Rust, and advanced ML models
→ GitHub Repo: sherlock-project/sherlock ⭐ 82,942 · Python