It depends on the registry, and on GitHub there is a hard limit. You cannot delete a public package if any version has more than 5,000 downloads, and you must contact GitHub Support instead. Even where deletion is allowed, it can break everyone who pulls the image.
What GitHub documents
GitHub Packages, which hosts container images at ghcr.io, lets you delete an entire public package only if no version has more than 5,000 downloads, and a specific public version only if that version does not exceed 5,000 downloads. Above that, the documentation says to contact GitHub through the Support portal. It also warns that deleting public packages may break projects that depend on them.
For restoration, GitHub allows restoring a package or version within 30 days of deletion, provided the same namespace is still available and unused.
I did not confirm limits for other public registries in the sources checked, so check the registry you publish to.
Why the rule exists
A widely used public image is infrastructure for people you may never meet. Removing it can stop builds across many projects at once. History in package ecosystems shows that sudden removals cause outages for downstream users, so registries add friction. The friction is a feature.
What maintainers should do instead
| Goal | Better than deleting |
|---|---|
| Stop people using a vulnerable version | Publish a fixed version and mark the old one deprecated in the README and release notes |
| Retire a project | Announce an end of life date, keep the last image available, and point to a replacement |
| Remove a leaked secret in an image | Rotate the secret first, then remove the image, since deleting does not undo exposure |
| Rename an image | Publish under the new name and keep the old one for a transition period |
See unpublish, yank, deprecate: compare registry removal options for the same trade off in package registries.
What consumers should assume
If you depend on a public image, assume it can vanish or change. Mirror what you need into a registry you control, and pin by digest so you know what you run. See mirror docker hub images with a pull through cache and registry proxy blocked a package: exception workflow.
A pull through cache or internal copy also protects you from deletion by the publisher. It does not protect you from a compromised image, so keep scanning what you cache.
If you maintain a popular image
- Keep at least two people with admin rights on the package.
- Write down an end of life process before you need it.
- Prefer deprecation notices to deletion.
- Document how consumers can verify what they pull.
Tell people what changed
Whatever you decide, say it where users look: the image description, the repository README and your release notes. State which versions are affected, what to move to, and by when. Clear notice costs a few minutes and saves downstream teams from debugging a failing pull with no explanation.
Quick check
Is the 5,000 download limit the same on every registry?
No. It is GitHub's documented rule for packages. Check the registry you use.
Does deleting a public image remove a leaked secret?
No. Anyone who pulled it still has it. Rotate the secret first.
Sources
Last reviewed: 19 October 2026.
