npm's replace-registry-host setting decides whether the resolved URLs stored in package-lock.json are rewritten to point at the registry you have configured. The default, npmjs, rewrites only URLs from the public registry. Other values are never, always, a hostname or a URL prefix.
Why this matters
A lockfile entry stores a resolved URL, the address of the tarball, plus an integrity hash. If your team installs through an internal mirror, a lockfile created on a laptop that talks to the public registry names the public host. In CI, which is configured to use the mirror, npm must decide: fetch from the host in the file, or from your configured registry?
That choice affects both reliability and security. If CI quietly goes to the public host, you bypass the mirror's scanning and allowlist. If it always uses the mirror, you get consistency, as long as the mirror serves identical bytes.
The documented values
| Value | Behavior |
|---|---|
| npmjs (default) | Replace package URLs from the default registry, https://registry.npmjs.org, with the configured registry |
| never | Use the value in the lockfile as written |
| always | Replace the registry host with the configured host every time |
| a bare hostname | Replace only URLs coming from that host |
| a full URL with a path | Replace the whole matching prefix with the configured registry URL, without duplicating path segments |
The last form is useful when you are moving between mirrors and old lockfiles name a path on a previous host.
The integrity field is the safety net
Rewriting the host does not change the integrity hash in the lockfile. Our post on what the npm lockfile integrity field protects explains the follow-on effect: if a mirror serves different bytes for the same name and version, the hash will not match and the install fails. So a rewrite is safe against a tampering mirror as long as you keep the hashes in the lockfile.
Choosing a value
- If everyone, laptops and CI, uses the same registry, leave the default.
- If CI must never reach the public registry, set it to always in the project .npmrc and verify with a network block in CI that nothing leaks.
- If you are migrating mirrors, use the URL prefix form for a transition, then regenerate the lockfile.
- If you need lockfiles to remain untouched for audit purposes, use never and make sure your registry setting matches the lockfile.
# .npmrc (project)
registry=https://npm.internal.example/
replace-registry-host=always
Test the result by running a clean install with the network restricted to your mirror. Any request to another host indicates a setting is missing.
Related controls
Pair this with registry scoping. A scope can point at a private registry, as in pointing an npm scope at a private registry, and the npmrc rule that credentials are scoped to a registry prevents sending a token to the wrong host.
A caution on versions
This description comes from the current npm CLI configuration source. Confirm the behavior for your installed version with the npm config help before changing policy.
Where Safeguard fits
Safeguard's SBOM and dependency scanning read what the lockfile resolves, and policies and gates can check that components match the rules you set. A free scan is at https://gold.safeguard.sh/scan.
Quick check
What is the default value of replace-registry-host?
npmjs. npm rewrites resolved URLs that point at the public registry to your configured registry, and leaves others alone.
Does rewriting the host change the integrity hash?
No. The integrity value stays in the lockfile, so differing bytes from a mirror fail verification.
Sources
Last reviewed: 19 October 2026.
