Sherlock writes a file per username, and its distro packages are somebody else's job

The help text in the README is a release behind the package

The usage block printed in the README ends with a version line:

Sherlock: Find Usernames Across Social Networks (Version 0.16.0)

The package is not at 0.16.0. The pyproject.toml in the same repository says version = "0.16.2", and the most recent release is v0.16.2 dated 2026-09-08. The three most recent releases listed are v0.16.2, v0.16.0, and v0.15.0 from 2024-07-08, with v0.16.1 absent from that list entirely.

The flag list above the version line is the practical problem. It is a snapshot taken from 0.16.0:

usage: sherlock [-h] [--version] [--verbose] [--folderoutput FOLDEROUTPUT] [--output OUTPUT] [--csv] [--xlsx] [--site SITE_NAME] [--proxy PROXY_URL] [--dump-response]
                [--json JSON_FILE] [--timeout TIMEOUT] [--print-all] [--print-found] [--no-color] [--browse] [--local] [--nsfw] [--txt] [--ignore-exclusions]
                USERNAMES [USERNAMES ...]

So a reader planning a pipeline from the README is planning against a two-patch-old interface. Run the version flag on your own install and read your own help output instead of copying this block.

PyPI renders a different README from the one on GitHub

The packaging metadata points the long description at a file that is not the front page. In pyproject.toml the readme field is set to docs/pyproject/README.md, while the repository's own README.md sits at the top level. The packages field includes sherlock_project, and the project links to PyPI and to a Homebrew formula in its reference links.

That means the long description a user sees on the package index is rendered from a file nested under docs/pyproject/, and the two documents are maintained in different places. The GitHub front page you read while evaluating the tool is not the page that appears after you install it.

For a reader this is a small but real trust gap. Once someone reads the same project on PyPI, they are reading a document maintained somewhere else, and a discrepancy between the two is invisible unless you open both. Check the index page against the repository if the details matter to you.

The dnf install row carries no notes and no maintainer name

The installation table has three rows. The first is pipx install sherlock-project, with a note that pip or uv may be used in place of pipx. The second is docker run -it --rm sherlock/sherlock. The third is dnf install sherlock-project, and its notes cell is empty.

That empty cell matters because of the sentence underneath. Community-maintained packages are available for Debian 13 and later, Ubuntu 22.10 and later, Homebrew, Kali, and BlackArch, and the README is explicit that these packages are not directly supported or maintained by the Sherlock Project. The community list does not include dnf, and the row that would explain who ships the dnf package says nothing at all.

So the one install method with no stated owner is also the one no other sentence covers. Then there is the warning above the table: packages for ParrotOS and Ubuntu 24.04, maintained by a third party, appear to be broken, and users of those systems are told to defer to uv, pipx, pip, or Docker. For anyone on Kali or BlackArch, the two distributions most associated with this kind of work, the package is community-run and the project says so in those words.

Two CHANGE ME ON UPDATE build arguments decide what the image installs

The Dockerfile does not install the source tree it is built from. It installs a named version from PyPI, and the version comes from a build argument that has no default:

ARG VCS_REF= # CHANGE ME ON UPDATE
ARG VERSION_TAG= # CHANGE ME ON UPDATE
RUN pip3 install --no-cache-dir sherlock-project==$VERSION_TAG

The release instructions live in a comment at the top of the same file. Update the version tag in the Dockerfile to match the version in sherlock/__init__.py, update VCS_REF to the tagged version's full commit hash, and build the image with both a version tag and latest, for example docker build -t sherlock/sherlock:0.16.0 -t sherlock/sherlock:latest .

Two consequences. The image's contents are decided by an argument somebody types, not by the commit the image was built from, and the commit hash and the version are recorded only as labels, so a wrong argument produces an image that still runs and still claims a provenance it does not have. And a version number now lives in at least three places, pyproject.toml, sherlock/__init__.py, and this ARG. Since the instructions are comments rather than a check, nothing enforces that they agree.

The dependency floor is 3.9 while the classifiers claim 3.10 through 3.13

The dependency table sets python = "^3.9". The classifier list above it advertises Programming Language :: Python :: 3, then 3.10, 3.11, 3.12, and 3.13. There is no 3.9 classifier, and the package is marked Operating System :: OS Independent.

So the resolver will happily install on 3.9 while the metadata makes no claim about 3.9 at all. That is a narrow gap, but it is the kind of thing that shows up as an unclassified install in a bug report rather than as an error. The Docker image sidesteps the question by pinning python:3.12-slim-bullseye for both the build stage and the runtime stage.

A second detail affects anyone vendoring the dependencies. There is no requirements.txt at the top level. The tree holds pyproject.toml, pytest.ini, tox.ini, sherlock_project/, tests/, devel/, and docs/, and the build backend is poetry.core.masonry.api. The version constraints are written in poetry's caret syntax, so pip cannot consume them directly. If you need the dependency set inside an environment you manage yourself, you either bring poetry or you translate the list by hand.

--ignore-exclusions turns a research tool into a guess generator

The dependency list includes certifi, colorama, PySocks, requests, requests-futures, stem, pandas, openpyxl and tomli.

Set against that, the flag list includes --site to restrict the search, --timeout, --json, --txt, --output, --folderoutput, --browse, --local, --nsfw, --print-all, --print-found, --dump-response, and --ignore-exclusions.

That last flag is the one to read carefully. The flag name suggests it turns off the exclusion filtering, so check the project documentation for exactly what is excluded before turning it on.

Every search writes a text file named after the username you searched

Basic usage is a single command, sherlock user123, or several at once, sherlock user1 user2 user3. Results are not only printed. The README states that accounts found will be stored in an individual text file with the corresponding username, for example user123.txt.

That default is the part worth planning around. Every username you look up produces a file named after it, written into whichever directory you ran the command from, and it stays there. Search ten handles from a home directory and you have ten files recording which ten handles you were interested in. The --output and --folderoutput flags let you redirect that, and --csv, --xlsx, and --json give you structured forms instead.

The consequence is a durability question rather than a correctness one. The output is a durable artefact of your research, sitting in a working directory that gets committed, synced, or backed up as a matter of habit, and Sherlock does not clean it up for you. On a shared machine or a laptop with cloud sync, point the output somewhere deliberate before the first search rather than after.

Editorial conclusion

Sherlock suits an investigator or a journalist checking whether a handle exists, on a machine where pipx, uv, or Docker is the install path and the results directory is one you control. It does not suit anyone treating it as an account takeover tool, since it reports whether a username is taken and nothing more, and its own metadata labels it reconnaissance. Before running it, check the version with the version flag rather than the README's help text, decide where the per-username text files land, and leave the exclusion filtering on unless you have a reason not to.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes