Verify npm Package or Archive Integrity Before Installing

Verify npm Package or Archive Integrity

The npm registry stores a SHA-512 integrity hash for every published package version. When you download a tarball manually or receive one from a colleague, comparing its hash against the registry entry confirms you have the authentic, unmodified package rather than a tampered version.

How npm's integrity field and SRI format protect package consumers

The npm registry stores a SHA-512 hash for every published package version in a field called integrity. Formatted as a Subresource Integrity (SRI) string, this value begins with "sha512-" followed by a base64-encoded representation of the hash, for example: sha512-v2kDEe57lecTulaDIuNTPy3Ry4gIPhqjtVGJqZkGLx5KrSvHOkqdmdQEF9igwMgTEDT9EPYFNnb9FBWP3FJw==.¹ When npm installs a package, it downloads the tarball, computes its own SHA-512 hash, and compares the result against the registry's stored integrity value; a mismatch causes the installation to fail with an integrity check error.²

Package-lock.json records the integrity value for every installed dependency at the version pinned during the last npm install.³ Running npm ci instead of npm install enforces that every installed package matches the version and integrity value recorded in package-lock.json, rejecting any package that produces a different hash.⁴ On build servers and in CI/CD pipelines, npm ci provides stronger integrity guarantees than npm install because it cannot silently update packages to new versions or accept modified tarballs.

Finding and converting the expected hash for comparison

Running npm view <package>@<version> dist.integrity in a terminal returns the SHA-512 SRI value for any published version, with no local install required.⁵ For packages already in your project, open package-lock.json and search for the package name; the "integrity" field contains the sha512-prefixed SRI value from your last install. The SRI format differs from the raw hexadecimal that most hash tools output. To convert between formats on Linux or macOS, run openssl dgst -sha512 -binary <file> | openssl base64 -A to produce base64 without the SRI prefix, then prepend "sha512-" before comparing against the npm integrity value.⁶

The base64 conversion matters because the tool on this page outputs raw hex by default. A hex string never matches an SRI string directly, so the conversion step is what makes a manual terminal comparison possible. If you skip it and compare hex against the registry's base64 value, every package will appear to fail even when the bytes are identical. Matching an npm tarball to the registry's integrity field skips the hex-to-base64 conversion entirely: drop the file into the tool and paste the integrity value directly.

Verifying npm tarballs in CI/CD pipelines and air-gapped environments

In CI/CD pipelines that cache node_modules or the npm cache directory between runs, a verification step after cache restoration confirms the cached files were not modified between builds. Running npm ci after restoring the cache uses package-lock.json's recorded integrity values as the reference and rejects any cached package that does not match. For pipelines where this automatic check is not sufficient, disable the node_modules cache and use npm ci to install directly from the registry on every run.

Air-gapped environments require npm packages to be bundled and transferred offline. The safest process runs in two stages: in a connected environment, download each tarball and verify its hash against the registry's dist.integrity value using npm view; then transfer the verified files to the air-gapped environment. After transfer, recompute each tarball's hash and compare against the pre-transfer reference to confirm no file was altered during the transfer process.

Auditing offline install bundles with hash verification

Organizations that maintain an approved package bundle for internal distribution benefit from per-tarball hash verification when assembling or auditing the bundle. Compare each tarball's SHA-512 hash against the corresponding npm view <package>@<version> dist.integrity value to confirm every file was sourced directly from the public registry without modification. Any tarball that does not match its registry hash was either corrupted after download, sourced from a non-registry location, or locally modified; each of these scenarios warrants investigation before including the bundle in a production deployment.

Diagnosing npm integrity check failures

An npm integrity error during npm install or npm ci reports the package name, the expected integrity value from package-lock.json, and the computed value from the downloaded tarball. When the computed value does not match the expected value in package-lock.json, the tarball on disk or in the npm cache is corrupted or replaced. If the expected value in package-lock.json does not match the registry's current dist.integrity for the same package version, the package-lock.json file was generated against a different registry state than the one currently returned.

Registry integrity values do not change after a package version is published under normal conditions.⁷ A mismatch between package-lock.json's recorded integrity and the registry's current value for the same version therefore warrants investigation: an integrity value change on an already-published version signals either a registry incident, an undocumented re-publish, or package-lock.json generated against a non-public registry. Before proceeding with installation, contact the package maintainer and check the project's security advisories.

Clearing the npm cache after an integrity failure

After an integrity check failure, clearing the npm cache before retrying prevents a corrupted cached tarball from producing repeated failures on subsequent runs. Running npm cache clean -f followed by a fresh npm install fetches new copies of all packages directly from the registry. If the failure recurs after a clean cache, the issue lies in the registry or package-lock.json rather than the local cache, and further investigation of the package's published state and your package-lock.json is necessary.

When to use this

Use this when installing packages from a private registry, verifying a tarball received by file transfer, confirming a package cached in a CI artifact store, or auditing an air-gapped install bundle.

Examples

File: lodash-4.17.21.tgz
Registry SHA-512 (base64): sha512-v2kDEe57lecTulaDIuNTPy3Ry4gIPhqjtVGJqZkGLx5KrSvHOkqdmdQEF9igwMgTEDT9EPYFNnb9FBWP3FJw==

Computed SHA-512: [matches registry value]
Result: MATCH