The Problem
Manually verifying username availability across social networks is slow and error-prone. Brand protection, social media monitoring, and security research all require checking a username against hundreds of platforms, which is impractical to do by hand.
What This Does
Sherlock is a Python CLI that checks a given username against 400+ social networks. It sends HTTP requests to each site's profile URL and analyzes the response to determine whether the account exists. Results are written to text, CSV, or XLSX files, or printed to the terminal with color-coded output.
The core logic lives in sherlockproject/sherlock.py (query orchestration), sherlockproject/sites.py (site definitions), and sherlockproject/result.py (result handling). The site database is a JSON file at sherlockproject/resources/data.json with a schema at data.schema.json. The CLI entry point is sherlockproject/main.py, which parses arguments like --csv, --proxy, --timeout, and --site for filtering.
How To Use It
Setup: Install via pipx install sherlock-project, or run the Docker image. A Dockerfile exists at the repo root, and pyproject.toml defines the Python package. The README warns that some distro packages (ParrotOS, Ubuntu 24.04) are broken, so pipx or Docker is safer.
Configuration: No environment variables or config files are required. The site list lives in sherlockproject/resources/data.json; you can load a custom JSON file with --json. Use --local to force the bundled dataset instead of fetching an updated one.
Running it:
Check a single username
sherlock user123
Check multiple usernames
sherlock user1 user2 user3
Limit to specific sites, save as CSV
sherlock --site github --site twitter --csv user123
Real-World Use
A security analyst monitoring for impersonation accounts can run sherlock --csv --output findings.csv "companyname" daily, then diff the CSV against the previous day's output. The --proxy flag supports socks5, which is useful when running from a restricted network. For automated pipelines, the Docker image (docker run -it --rm sherlock/sherlock) gives a clean, isolated environment.
Code Health & Issues
Low - No dependency lockfile - pyproject.toml declares dependencies but no lockfile (e.g., uv.lock or poetry.lock) exists. Builds are not fully reproducible. Low - Large single JSON site database - sherlockproject/resources/data.json is the critical data source. It's updated by a GitHub Action (.github/workflows/update-site-list.yml), which is good, but a malformed entry can break all checks. Med - Reliance on HTTP response heuristics - Sherlock infers account existence from response codes and page content. Sites that block bots or return generic 200s will produce false positives/negatives. The project acknowledges this via false-positive.yml and false-negative.yml issue templates. Good - Test coverage exists - 9 test files under tests/ cover probes, UX, manifest, and site validation. GitHub Actions workflows (.github/workflows/regression.yml, validatemodified_targets.yml) run these in CI. Good - Structured contribution process - Issue templates for site requests, bug reports, and false positives/negatives indicate a mature maintenance workflow.
The Bottom Line
Sherlock is a mature, actively maintained tool for username enumeration across social platforms. It's well-suited for security researchers, brand monitoring, and OSINT work. The lack of a lockfile is minor; the main caveat is that results depend on external sites' behavior, so treat output as intelligence, not ground truth.