# How to install and run Sherlock without fixing Python

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.

Published 25 Oct 2026 by OTInstaller.

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](https://otinstaller.com/docs/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](https://otinstaller.com/blog/run-osint-tools-in-docker) explains the container in full.

## No Docker? Use otlite

[otlite](https://otinstaller.com/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](https://otinstaller.com/docs/otlite) cover the rest.

## What the result looks like

`ot run` prints a JSON [result envelope](https://otinstaller.com/docs/results) and saves the run. This is the envelope from the GitHub
check above, shortened:

```json
{
  "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](https://otinstaller.com/blog/username-search-tools) sets Sherlock beside Maigret, naminter and socialscan, the
[username investigation guide](https://otinstaller.com/guides/osintverse-community/username-investigation) walks through a whole case, and
[every tool that takes a username](https://otinstaller.com/input/username) is listed on one page.