What does deprecating a published npm version do, and how does that differ from unpublishing it?

## Three different verbs, three different promises Once a version is public, strangers can resolve it. Everything you can still do to it falls into one of three buckets, and mixing them up is the most common confusion in this area. **Deprecate — a signal, attached to a version that stays.** You supply a message and a version selector; the registry stores that message against every matching version and serves it in the package metadata. Install clients surface it as a warning line. The tarball is untouched, the checksum is unchanged, resolution behaves identically, and a build that would have succeeded before still succeeds. It is purely advisory, and it is reversible: setting the message to an empty string removes the deprecation. **Yank (crates.io, and PyPI's equivalent) — withhold from future selection, delete nothing.** A yanked version stops being an eligible candidate for new dependency resolution, but the files remain downloadable and anything that already pins the exact version keeps working. It sits between the other two: stronger than a warning, weaker than removal, and also reversible. **Unpublish / delete — the bytes stop being served.** Only this one actually takes something away. A fresh attempt to download the exact version fails. ## Why deprecation is the usual answer A published version is an input to other people's builds. Removing it turns their working pipeline into a failing one, at a moment they did not choose, for a reason they have to go and discover. That is why registry policy fences unpublish so tightly. npm permits a straightforward unpublish only very soon after the version was pushed, and after that only under narrow conditions such as nothing depending on it; beyond that you are asking a human at the registry for an exception. On Maven Central, released coordinates are immutable by policy — the guarantee that a given group, artifact and version always maps to the same bytes is the whole point, and it is worth more to the ecosystem than your ability to retract a mistake. PyPI does let you delete files, with a catch covered below. So the honest mental model is: **publishing is close to irreversible, and your post-publication toolkit is mostly about signalling, not about recall.** ## What each one does to an existing lockfile This is the question interviewers actually use to test whether you understand the difference. | Action | Existing lockfile | New resolution | Files still downloadable | |---|---|---|---| | Deprecate | unchanged, installs fine | still selectable | yes | | Yank | unchanged, installs fine | not selected | yes | | Unpublish / delete | install of that version fails | not selectable | no | Notice that in two of the three rows a team already on the bad version is entirely unaffected. Nobody is emailed. Nothing is recalled. If your goal is for existing consumers to move, none of these three verbs achieves it on its own. ## The limit of a deprecation message as a security channel Deprecation warnings are read by roughly nobody. A real project's install output already carries deprecation lines from a dozen transitive packages it never chose, and the whole block scrolls past in a CI log. If you deprecate three minor versions of a widely used package because they carry a security flaw, you have added noise to a stream that was already ignored. That is not a reason to skip deprecating — it is cheap and it helps the person who does read it — but it means the message is a courtesy, not a notification mechanism. The channel that actually reaches consumers is a published security advisory keyed to the affected version range, because scanners and update bots consume advisory feeds automatically and open a change against affected projects. Registry-side flags reach only the people who happen to resolve fresh. ## Filename and version immutability A related rule catches people out: on PyPI a deleted filename can never be reused. The registry will not accept a re-upload of the same file name even after deletion, precisely so that a name a consumer or a mirror recorded can never later mean different bytes. Practically, that means "delete the broken file and re-upload a fixed one under the same version" is not available — you publish a new version number. Immutability of a published identifier is the property the whole verification chain depends on, and every registry protects it in some form. ## The reflex to build When a bad version is out: publish the fixed version first, so consumers have somewhere to go; deprecate or yank the bad one so new adopters do not land on it; publish an advisory so tooling tells the people already on it; and reserve deletion for artifacts whose mere existence is the hazard.