With the .NET CLI, how do you publish with dotnet nuget push, and what can you do once a nuget.org release is broken?
answer
- --source plus --api-key
- 409 Conflict: a version is pushed once
- --skip-duplicate for reruns
- nuget.org unlists, never deletes
- unlisted still restores by exact version
basics
~20 sdotnet nuget push <file>.nupkg --source <feed> --api-key <key> uploads the package; a version can be pushed only once. nuget.org does not delete packages: you unlist the broken version, which hides it from search but keeps exact-version restores working, and ship a fixed version.
solid answer
~50 s`dotnet nuget push Shared.Validation.2.3.0.nupkg --source <feed> --api-key <key>` uploads the package; a `.snupkg` beside it is pushed too unless `--no-symbols`. Since NuGet 7.6 the key can come from `NUGET_API_KEY`, and `--skip-duplicate` turns a **409 Conflict** — that id and version already exist — into a warning, which keeps CI reruns green. A published version is effectively immutable: you cannot replace its contents. **nuget.org does not support deletion**; `dotnet nuget delete` against nuget.org **unlists** the version. An unlisted version disappears from search and the package page but can still be restored by exact version, so existing builds keep working, and floating ranges can still resolve to it if it is the best match. The fix is a new version (2.3.1), optionally with the broken one marked deprecated. Private feeds may allow real deletion, which breaks every build that referenced it.
code
bash · 7 lines# CI release step: idempotent push, key from the environment (NuGet 7.6+)
dotnet nuget push "artifacts/*.nupkg" \
--source https://api.nuget.org/v3/index.json --skip-duplicate
# a broken release on nuget.org: this unlists, it does not delete
dotnet nuget delete Shared.Validation 2.3.0 \
--source https://api.nuget.org/v3/index.json --api-key "$NUGET_API_KEY" --non-interactivego deeper
Recall dotnet nuget push with a source and API key, and that a broken nuget.org version is unlisted rather than deleted.
Explain 409 Conflict and --skip-duplicate, symbol pushes, NUGET_API_KEY, and exactly what unlisting hides and what it leaves restorable.
Run releases safely: push the tested artifact once, keep keys in secrets, fix forward with a new version, and avoid real deletion on private feeds.
Own the release and recall policy for internal packages: immutability, deprecation, and how consumers are told to move off a bad version.
## Pushing a package After `dotnet pack`, publishing is one command: ```bash dotnet nuget push artifacts/Shared.Validation.2.3.0.nupkg \ --source https://api.nuget.org/v3/index.json --api-key "$NUGET_API_KEY" ``` Options that matter in practice: | Option | Purpose | |---|---| | `-s`, `--source` | the feed URL or name; without it, the config's default push source | | `-k`, `--api-key` | the key that authorises the push | | `--skip-duplicate` | treat a 409 Conflict as a warning so other pushes continue | | `-n`, `--no-symbols` | do not push a symbol package even if one is present | | `-ss`, `--symbol-source` / `-sk`, `--symbol-api-key` | push symbols to a separate server | | `-t`, `--timeout` | seconds to wait, 300 by default | | `--configfile` | use only this nuget.config (since .NET 9 SDK) | Since **NuGet 7.6**, `NUGET_API_KEY` and `NUGET_SYMBOL_API_KEY` environment variables can supply the keys; the command-line option beats the variable, and the variable beats a key stored in `nuget.config`. Keeping the key in the pipeline's secret store and out of the command line keeps it out of logs. When a `.snupkg` with the same name sits next to the `.nupkg`, push sends the main package first and the symbol package after it. ## A version is published once A feed answers a second push of the same id and version with **409 Conflict**. That is the immutability contract consumers rely on: `Shared.Validation 2.3.0` means the same bytes everywhere, forever. In CI, `--skip-duplicate` lets a re-run of a release job pass instead of failing on packages it already pushed — it does not overwrite anything. ## When a released version is broken nuget.org's policy is explicit: **permanent deletion is not supported**, because it would break every project that depends on the version. Exceptions are made only by the NuGet team for policy violations such as malware or infringement. What the owner can do: 1. **Unlist** the version — on the package management page or with `dotnet nuget delete Shared.Validation 2.3.0 --source <nuget.org> --api-key <key>`, which on nuget.org unlists rather than deletes. 2. **Publish a fix** as a new version, 2.3.1. 3. Optionally **deprecate** the bad version so clients show a warning and point to the alternative. What unlisting does and does not do: - The version no longer appears in search, in the Visual Studio UI or on the public package page. - It **can still be downloaded and restored by exact version**, so every existing lock file and pinned reference keeps building. - **Floating versions** may still resolve to an unlisted version if it is the best match, and the catalog still replicates it. So unlisting reduces new adoption; it does not recall the bytes. That is why the fix must be a new, higher version. ## Private feeds differ `dotnet nuget delete` "deletes or unlists" depending on the server. A private feed may truly delete a version, which then breaks every build that referenced it — the same failure nuget.org's policy exists to prevent. Teams publishing an internal library usually adopt nuget.org's rule anyway: never delete, unlist and supersede. ## Deprecation versus unlisting The two tools answer different needs: | Action | Visible in search | Restorable | Consumers warned | |---|---|---|---| | unlist | no | yes, by exact version | no | | deprecate | yes | yes | yes, with reason and alternative | Deprecation lets owners mark a version as legacy, as having critical bugs, or for another reason, and name an alternative package or version; Visual Studio and `dotnet package list --deprecated` surface it to consumers who already use it. Deprecating does not unlist. For a version with a serious bug, owners often do both: deprecate so existing consumers find out, and unlist so new consumers do not pick it. ## A release pipeline sketch - Pack once, push the same artifact that was tested. - Push with `--skip-duplicate` so a retried job is idempotent. - Tag the commit with the package version so a broken release can be traced and fixed forward.
- Why does unlisting not stop an existing service from restoring the broken version?Unlisted versions stay downloadable by exact version so restores never break; they are only hidden from search and package pages. A service pinned to 2.3.0 keeps getting it until its reference moves to 2.3.1.
- What does --skip-duplicate actually change?When the server replies 409 Conflict because the id and version already exist, push logs a warning and continues instead of failing. It never overwrites the existing package; it only makes a re-run of the same release idempotent.
- You can overwrite a published nuget.org version by pushing it again.
- --skip-duplicate replaces the existing package with the new upload.
- dotnet nuget delete removes the version from nuget.org permanently.
- Unlisting stops all builds from restoring that version.
- Floating version ranges never resolve to an unlisted version.
Assumes the .NET 10 SDK with NuGet 7; NUGET_API_KEY and NUGET_SYMBOL_API_KEY are honoured from NuGet 7.6 (SDK 10.0.300) on, and push's --configfile option exists since the .NET 9 SDK.