npm deprecate: Usage & Common Errors

Warn users away from a published version.

npm deprecate attaches a deprecation message to a published version or semver range, which npm prints when anyone installs it.

What it does

Sets a deprecation warning on the matching versions in the registry without unpublishing them - installs still work but emit the message. Passing an empty string ("") as the message clears the deprecation. You must be an authenticated owner.

Common usage

npm deprecate my-pkg@"<2.0.0" "Upgrade to 2.x; 1.x is unsupported"
npm deprecate my-pkg@1.4.2 "Security issue, use 1.4.3"
npm deprecate my-pkg@1.4.2 ""        # un-deprecate

Common error: deprecate requires auth/ownership

npm deprecate fails with a 403/E403 when the token is not an owner of the package or lacks permission. Use an automation token belonging to a maintainer (or the owning org) and confirm with npm owner ls before running it in a pipeline.

npm owner ls my-pkg          # confirm ownership first

Related guides