OTInstaller
Sign in

Blog

How to install and run Sherlock without fixing Python

· OTInstaller

Why pip install sherlock goes wrong, and how to run Sherlock 0.16.2 in one command with ot, or with otlite on a machine without Docker.

To install and run Sherlock without fixing Python, install ot and run ot run osintverse-community/sherlock u:johndoe. The first run installs Sherlock 0.16.2, its current release, from PyPI, checks it against a pinned SHA-256, builds it into a container image of its own and searches 400+ sites for the username. Your own Python is never involved. On Linux or macOS without Docker, otlite install sherlock and then otlite run sherlock -- u:johndoe do the same in a virtualenv of their own.

Where the usual install goes wrong

Sherlock is a Python program, published on PyPI as sherlock-project, and its README suggests installing it with pipx. These are the places it trips people up:

  • The wrong name. pip install sherlock succeeds, but installs an unrelated library for distributed locks. The package you want is sherlock-project; the command it installs is sherlock.
  • An old Python. Release 0.16.2 needs Python 3.9 or newer. On Python 3.8 pip doesn’t fail: it quietly installs 0.15.0, from July 2024, instead.
  • A system Python that refuses. On Debian 12, Ubuntu 23.04 and later, and current Kali, pip install outside a virtualenv stops with error: externally-managed-environment. The usual workaround, --break-system-packages, does what its name says.
  • Requirements that conflict. 0.16.2 asks for pandas below 3.0, stem below 2.0 and requests-futures below 2.0, among others. pandas 3 has been out since January 2026, so in an environment shared with a tool that needs it, one of the two ends up with a version it did not ask for.

pipx avoids the last two by giving every program its own virtualenv. You still need pipx and a suitable Python first, the same steps again for every other tool, and nothing records which version produced a result.

Run it with ot

Install ot and check the machine:

curl -fsSL https://get.otinstaller.com/ot | sh     # macOS and Linux
irm https://get.otinstaller.com/ot.ps1 | iex       # Windows PowerShell
ot doctor

ot needs Docker Desktop or Podman running, and ot doctor says so if it isn’t. Then run Sherlock:

ot run osintverse-community/sherlock u:johndoe

u: says the value is a username. Because Sherlock isn’t installed yet, ot asks once (Install it now? [Y/n]), then:

  1. downloads the sherlock-project 0.16.2 wheel from PyPI and checks it against the SHA-256 in the package’s manifest;
  2. builds it into a small image on python:3.12-slim, so Sherlock’s requirements live there and nowhere else;
  3. runs it in a container that is read-only, has no Linux capabilities and cannot see your files, with network access because Sherlock declares that it needs it.

The first run also prints warning: osintverse-community/sherlock is not signed. Sherlock’s releases on PyPI carry no signed provenance, so the hash is what holds the version in place: a wheel with any other SHA-256 is refused.

The package runs Sherlock with --print-found --no-color --timeout 20, so only accounts that exist are printed and each site gets 20 seconds to answer. A full search covers 400+ sites, and ot stops it after 15 minutes. Sherlock also downloads its current list of sites from data.sherlockproject.xyz each time it starts, so a run fails if that can’t be reached. To check a single site, add --site:

ot run osintverse-community/sherlock u:github --site GitHub

Once installed, that run took 8 seconds on our test machine (22 over a slow connection). Later runs start straight away, and ot update --all moves you to newer releases when the registry has them. Running OSINT tools in Docker explains the container in full.

No Docker? Use otlite

otlite is the edition for Linux and macOS without a container engine. It installs each tool into its own virtualenv under ~/.otlite, from a catalog that pins Sherlock to the same 0.16.2 release:

curl -fsSL https://get.otinstaller.com/otlite | sh
otlite init
otlite install sherlock
otlite run sherlock -- u:johndoe

The installer uses your Python and pipx when both are there, and otherwise installs otlite with uv on a Python 3.12 of its own, without sudo, so an old system Python doesn’t matter. Sherlock then runs directly on your machine rather than in a container, and each run is saved in the same results/ layout as ot’s, with a .meta.json and an .envelope.json beside it. The otlite docs cover the rest.

What the result looks like

ot run prints a JSON result envelope and saves the run. This is the envelope from the GitHub check above, shortened:

{
  "envelope": 1,
  "tool": "osintverse-community/sherlock@0.16.3",
  "runtime": "pipx",
  "input": {"site": "GitHub", "username": "github"},
  "started_at": "2026-10-25T09:19:13Z",
  "duration_ms": 7546,
  "exit_code": 0,
  "entities": [
    {"type": "url", "value": "https://www.github.com/github", "confidence": "low", "attrs": {"found_in": "text output"}},
    {"type": "domain", "value": "www.github.com", "confidence": "low", "attrs": {"found_in": "text output"}}
  ],
  "raw": "[*] Checking username github on:\n\r\n[+] GitHub: https://www.github.com/github\n\n[*] Search completed with 1 results\n…",
  "run_id": "6f18df7a",
  "artifact": {"kind": "wheel", "ref": "sha256:7f1341dcd554a39d529bcfff14b133410e8773e3e1083fc5bdd0cd0a579fb46f"},
  "output": {"path": "results/sherlock/github/20261025-091913_sherlock_github_6f18df7a.txt"}
}
  • tool is the registry’s package and its version. Package 0.16.3 installs Sherlock 0.16.2: an extra patch number marks a change to the packaging, such as its README, not to Sherlock.
  • entities is what the run found. Sherlock prints text rather than JSON, so ot lists the URLs and domains its output mentions, marked "confidence": "low". They are pattern matches: Sherlock 0.16.2 ends every search with a link to another service, and that link is listed too, so read them before you rely on one.
  • raw is exactly what Sherlock printed.
  • artifact is the exact wheel that ran, by its hash.
  • output.path is the saved copy. Next to it, a .meta.json holds the command as run, the timing, the exit code and status, the entities and the same provenance.

What to run next

  • ot runs lists saved runs, newest first, and ot runs 6f18df7a shows one with everything it found.
  • ot run osintverse-community/maigret u:johndoe checks 3,000+ sites (the 500 most popular by default) and adds the details the profiles expose. ot playbook username-investigation u:johndoe runs Sherlock and Maigret together.
  • ot extract sherlock collects the URLs and domains from every saved Sherlock run, and ot diff sherlock johndoe shows what changed between the last two runs against that username.
  • ot pivot 6f18df7a suggests what to run next on each thing the run found.

Username search tools sets Sherlock beside Maigret, naminter and socialscan, the username investigation guide walks through a whole case, and every tool that takes a username is listed on one page.

More posts · Changelog · This post as Markdown

Esc

Try

↑ ↓ to move↵ to open