# How do I check an npm package before installing it?

Source: https://getaiguard.dev/guides/check-npm-package · Last updated: 2026-11-14 · AI Guard 1.4.7

Run `npm view <name>` to see whether the package exists, who publishes it and when it was released, then compare the name with the package you meant. To automate the same checks, run `npx ai-guard verify-deps <name>`: it blocks names that don’t exist, removed malware and suspicious look-alikes, and warns on new, rarely downloaded, deprecated or very fresh releases.

## By hand with npm view

`npm view` reads the package document from the registry without installing anything. Three things to look for:

1. **Does it exist?** A name that was never published returns `E404`.
2. **Who publishes it, and is it a placeholder?** A version ending in `-security` published by `npm` means npm removed the original package, usually for malware.
3. **Is it the name you meant?** Compare it letter by letter with the popular package; `crossenv` is not `cross-env`.

A name that does not exist:

```console
$ npm view ai-guard-demo-no-such-package
npm error code E404
npm error 404 Not Found - GET https://registry.npmjs.org/ai-guard-demo-no-such-package - Not found
npm error 404
npm error 404  'ai-guard-demo-no-such-package@*' is not in this registry.
```

A package npm removed and replaced with a placeholder:

```console
$ npm view crossenv

crossenv@0.0.2-security | Proprietary | deps: none | versions: 4
security holding package
https://github.com/npm/security-holder#readme

maintainers:
- npm <npm@npmjs.com>

dist-tags:
latest: 0.0.2-security
```

(Output trimmed: the `dist` lines are omitted.) For publish dates, `npm view <name> time --json` lists when each version was published; downloads are on the package's npmjs.com page.

## Automatically with ai-guard verify-deps

`verify-deps` does those lookups for you and turns them into a verdict. Run it on names, on what a change adds, or on everything:

```bash
npx ai-guard verify-deps lodash expresss   # packages you name
npx ai-guard verify-deps                   # dependencies added since HEAD
npx ai-guard verify-deps --base main       # dependencies this branch adds
npx ai-guard verify-deps --all             # every dependency in the repository
```

Real output for four packages:

```console
$ npx ai-guard verify-deps ai-guard-demo-no-such-package

  AI GUARD

  Dependencies  ·  1 package  ·  1 blocked  ·  0 warnings

  command line
          error  ai-guard-demo-no-such-package  "ai-guard-demo-no-such-package" does not exist on npm. AI assistants often invent package names, and anyone can register an invented name later. package-not-found
```

```console
$ npx ai-guard verify-deps crossenv

  AI GUARD

  Dependencies  ·  1 package  ·  1 blocked  ·  0 warnings

  command line
          error  crossenv  npm removed the package published as "crossenv" (usually for malware) and replaced it with an empty placeholder. Did you mean "cross-env"? security-holding
```

```console
$ npx ai-guard verify-deps expresss

  AI GUARD

  Dependencies  ·  1 package  ·  0 blocked  ·  1 warning

  command line
          warn   expresss  "expresss" looks like the popular package "express". Make sure it is the package you meant. lookalike-name
```

```console
$ npx ai-guard verify-deps lodash

  AI GUARD

  Dependencies  ·  1 package  ·  0 blocked  ·  0 warnings

  ✔  1 package checked, nothing to report
```

The first two exit with code 1 (blocked); `expresss` and `lodash` exit with 0. Add `--fail-on warning` to fail on warnings too. Exit code 2 means some packages could not be checked, for example with no network; a check that did not run is never a pass.

## What is blocked and what is a warning

| Blocked | Warning |
| --- | --- |
| The package does not exist on npm | Look-alike of a popular package that is established |
| The exact version or dist-tag does not exist | First published less than 30 days ago |
| npm replaced it with a security placeholder | Fewer than 100 downloads last week |
| Look-alike of a popular package that is new or rarely downloaded | Runs an install script |
| Install script on a new or rarely downloaded package | Deprecated |
| | The version was published in the last 24 hours |

The thresholds are options: `--min-age` (days), `--min-downloads` (per week) and `--fresh-hours`. More on [the package checks page](https://getaiguard.dev/package-checks).

## Limits

- Blocking only on facts means some malicious packages pass with a warning. `expresss`, registered in 2016 with about 755 downloads a week, gets a look-alike warning, not a block.
- Network use is opt-in and only queries the public npm registry. Packages from private registries are skipped, so they are not checked.

## Sources

- [docs/cli/verify-deps.md: every check and option](https://github.com/ai-guard-dev/eslint-plugin-ai-guard/blob/main/docs/cli/verify-deps.md)
- [docs/evidence.md: results on real projects](https://github.com/ai-guard-dev/eslint-plugin-ai-guard/blob/main/docs/evidence.md)
- [npm docs: npm view](https://docs.npmjs.com/cli/v11/commands/npm-view)
