👻 What package hallucination is

Large language models complete patterns. When a task calls for a package that handles JWT authentication for FastAPI, a model may produce a plausible name whether or not anyone published it. A USENIX Security study of 576,000 generated code samples reported average hallucination rates of at least 5.2% for commercial models and 21.7% for open-source models, including 205,474 unique invented package names.

Repeated phantom names create an opening for slopsquatting: someone can register a suggested name and wait for later users to install it. Package existence is therefore worth checking separately from vulnerability data.

🚦 What the verdicts mean

Verdict	Meaning
PHANTOM	The package is not in the registry. If a tool suggested it, the name was likely invented. Never pre-create internal names publicly; a squatter can claim them.
DANGER	The package exists, but it is both a near-miss of a popular name and young or barely downloaded. That combination is the classic squatting profile.
CHECK	Registered recently, rarely downloaded, deprecated, or one edit away from a popular package. Usually fine, worth thirty seconds of review.
OK	Established package. This says nothing about its quality, only that it is real and not an obvious impostor.

🕵️ What this tool checks

Every dependency in a pasted package.json (all dependency fields), requirements.txt (specifiers, extras, and markers are handled), pyproject.toml (PEP 621 and Poetry), or source code with import and require statements.
Node built-ins and the Python standard library are recognized and skipped, including modules removed in recent Python versions such as telnetlib.
Registration date and monthly downloads (npm) and first upload date (PyPI) for existence checks with context.
Edit distance against several hundred of the most-installed packages in each ecosystem, to catch reqeusts and lodahs before they catch you.

🛡️ How to protect yourself beyond this page

Treat dependency suggestions from AI tools as unverified input, the same way you treat their code.
Run the GitHub Action before dependency installation in pull requests.
Install from lockfiles in CI, so one bad npm install on a laptop cannot silently add a package.
Check the registry page before first install: publish date, download counts, repository link, and whether that repository actually contains the code.
Internal package names belong in a private registry with a scoped namespace, so nobody can shadow them publicly.

⌨️ Use it from your terminal or CI

The same checks run outside the browser as a zero-dependency command line tool and a GitHub Action, so a hallucinated dependency is caught before anything installs.

Check a project

npx github:JaydenYoonZK/package-reality-check

Reads the dependency manifests in the current folder (package.json, requirements.txt, pyproject.toml) and checks every name against the live npm and PyPI registries. Pass a path to check another project.

Fail the build on danger

npx github:JaydenYoonZK/package-reality-check --fail-on danger

Exits non-zero at your chosen severity: phantom, danger, warn, or never. Add --json for pipelines and --include-code to also scan import statements in source files.

One step in a workflow

- uses: JaydenYoonZK/package-reality-check@v1

The GitHub Action runs the same check on pull requests before dependencies install. The full workflow example lives in the README.

Full flags and the Action inputs are in the README.

💬 Frequently asked questions

No. Parsing happens in your browser, and the only network requests are package-name lookups sent directly to npm and PyPI. The source contains the complete browser and registry logic.

No, it is the expected result: the tool only sees public registries. It is also a useful prompt to check that your internal name is protected from public registration.

Edit distance cannot read intent. Forks and legitimately similar names will occasionally trip the check. The verdict text always says what the similarity is, so you can decide in seconds.

npm and PyPI. Other ecosystems are tracked on the issue tracker.

🌱 Why I built this

A code suggestion once handed me a package name that did not exist, one letter away from one that did. Registering that name would take a squatter a few minutes. Checking dependencies by hand got old fast, so I built the check I wanted to run before every install.