Spell the package name exactly, link to the official registry page for it, and pin the version. Readers copy install lines without reading closely, so a one character mistake in your docs, or a look-alike name from a search result, can send them to a different package than you meant.
How a wrong name gets installed
Package registries accept names that differ from a popular one by a character, a hyphen or an ordering. Anyone can publish them. A reader who mistypes an install command, or who copies from a forum post with a typo, may fetch one of these. The cause may be an honest mistake in a page or a deliberate look-alike. The result on the reader's machine can be the same: code they did not intend runs, often at install time.
Docs authors cannot control the registry, but they control the line that readers copy. That is a strong lever.
What to put in the docs
| Practice | Why it helps |
|---|---|
| Copy install lines from the registry page, never retype them | Removes typos |
| Link the official registry page next to the command | Gives readers a way to verify |
| Pin an exact version | Readers get the release you tested |
| Show the publisher or maintainer name where the registry supports it | A second thing to check |
| Mention scope or organisation prefixes when the official package uses one | A common difference between real and fake |
| Keep one canonical install page and point everything else to it | Fewer places to drift |
Steps for a docs maintainer
- Extract every install command from your docs with a search for the package manager keywords you use.
- Compare each package name to the one on the official registry page, character by character, or with a script that checks the names against an allow list.
- Add the allow list to the docs build, so a new or edited install line with an unknown package name fails review.
- Pin versions, and refresh them on a schedule. See should tutorials pin dependency versions.
- Search the web for your package name with common misspellings and report suspicious packages to the registry through its reporting route.
- Tell readers what to do if they installed the wrong one: remove it, rotate any credentials that were on the machine, and check recent changes.
Advice for readers
Before installing, open the registry page and check the name, the publisher, the release history and the project link. A brand new package with few downloads that claims to be a well known tool deserves suspicion. Test unfamiliar packages in a disposable environment first. See test a new package in a sandbox before adopting it.
Reduce the damage a bad install can do by running tutorials in a container or a virtual machine without your cloud credentials. Install scripts and post install hooks run with your permissions.
Try it yourself
An accurate inventory is how you notice a package that should not be there. Click through one.
Click through it at your own pace, or open it full screen.
Safeguard's dependency scanning and SBOM generation list every package in a project, so an unexpected name stands out, and continuous monitoring flags new advisories. The free scan is at https://gold.safeguard.sh/scan.
Quick check
Can docs authors prevent look-alike packages?
They cannot remove them from the registry, but exact names, official links and pinned versions make a mistaken install much less likely.
What should a reader do after installing the wrong package?
Remove it, rotate credentials that were on that machine, and review what changed. Report the package to the registry.
Last reviewed: 19 October 2026.
