Say what is wrong, which version fixes it, and what to do. Keep it to one or two plain sentences, because npm shows the message to everyone who installs the deprecated version. Name a safe version or range, and link to an advisory if one exists.
How the command works
The npm documentation says the deprecate command updates the registry entry for a package, providing a deprecation warning to all who attempt to install it. It works on specific versions and on ranges, and its own example is a range with a short message about a critical bug fixed in a later version. Ranges passed to the command include prerelease versions. You must be a package owner, and passing an empty string as the message removes the deprecation.
npm deprecate my-package@"<2.4.1" "Security fix in 2.4.1, please upgrade. See the advisory linked from the repository."
Anatomy of a useful message
| Part | Example wording | Why |
|---|---|---|
| The reason | Security fix, or no longer maintained | Tells readers how urgent it is |
| The target | Upgrade to 2.4.1 or later | Gives a concrete action |
| The pointer | See the advisory on the repository | Lets people read details |
A message that only says "deprecated" leaves the reader to guess. A message that dumps exploit detail helps attackers. Aim for the middle.
Wording to avoid
- Vague text such as "do not use". Say why and what instead.
- Exploit instructions. Link to an advisory after a fix exists, rather than describing the attack in the install warning.
- Blame or jokes. The message appears in CI logs for thousands of builds.
- A range wider than you mean. Remember prereleases are included.
Deprecation is not removal
Deprecating leaves the version installable. It adds a warning, nothing more. Users who pin the old version keep getting it, and many pipelines ignore install warnings. For a version with a serious problem, also publish a fixed release, write an advisory, and read unpublish, yank or deprecate: comparing registry options.
A short sequence for a vulnerable release
- Publish the fixed version.
- Publish the advisory with the affected and fixed ranges.
- Deprecate the affected range with a message pointing to both.
- Mention it in the changelog. See mark a yanked release in your changelog for a format.
- Check that scanners show the same affected range you stated.
Examples by situation
For a security fix, a message might say that versions below a stated release contain a security issue fixed in that release, and point to the advisory. For an abandoned package, it might say the package is no longer maintained and name a successor, if one exists. For a version published by mistake, it might say it was released prematurely and name the correct version. In each case the reader learns the reason, the target and where to read more, without needing to open a browser. If you cannot recommend a successor, say that too, rather than implying one.
Review the exact range before running the command, because a range that is too wide will warn users on versions that are fine, and users learn to ignore warnings that cry wolf.
Quick check
Can I undo a deprecation?
Yes. The npm documentation says to pass an empty string as the message, written as double quotes with no space between them.
Does deprecating stop people from installing the version?
No. It only shows a warning. Pinned installs still work.
Sources
Last reviewed: 19 October 2026.
