npm-deprecate

Deprecate a specific version of a package

$ npm deprecate [package_name]@[version] "[deprecation_message]"

$ npm deprecate [package_name]@"<[version_range]" "[deprecation_message]"

$ npm deprecate [package_name]@[version] ""

npm deprecate <pkg>[@<version>] <message>
Note: To un-deprecate, use an empty string for the message.

<pkg>[@<version>]
    The name of the package to deprecate. Optionally, specify a particular version (e.g., 1.0.0) or a version range (e.g., 1.x, <2.0.0) to target. If no version is specified, all versions of the package will be deprecated.

<message>
    The deprecation message that will be displayed to users when they attempt to install the deprecated package version. Use an empty string "" to un-deprecate a previously deprecated version.

The npm deprecate command allows package maintainers to mark specific versions or a range of versions of their published packages as deprecated. When a user attempts to install a deprecated version, npm will display a warning message, indicating that the version should not be used. This feature is crucial for signaling various issues, such as security vulnerabilities, critical bugs, or encouraging users to upgrade to a newer, more stable version, or migrate to an entirely different package.

Deprecating a package version is a permanent action recorded in the npm registry. It helps guide the community towards healthier and more secure package usage patterns. Maintainers typically use this command when a version is no longer supported, has known issues, or an alternative package is now preferred.

Deprecation is a permanent action for a given version. While you can "un-deprecate" by setting an empty message, the record of deprecation remains in the registry.
Only package owners can deprecate versions of their packages.
The deprecation message, once set, cannot be directly edited for a specific version; you must un-deprecate and then re-deprecate with a new message.
The deprecation warning is displayed to users during npm install operations, not when the package is already installed.

To remove a deprecation warning from a package version, you simply run the npm deprecate command again for that specific version, but pass an empty string as the message. For example: npm deprecate my-package@1.0.0 ""

When a package version is deprecated, users who try to install it will see the specified deprecation message as a warning during the npm install process. This helps them identify potentially problematic dependencies and encourages them to update their package versions or consider alternatives.

The npm deprecate command has been a foundational part of the npm CLI since its early days, providing a critical tool for package maintainers to communicate the lifecycle status of their published modules. Its core functionality has remained stable over many npm versions, reflecting its importance in guiding developers towards current and secure package dependencies.

npm install(1), npm publish(1), npm owner(1), npm unpublish(1)