Package deletion and restoration support on GitHub
On GitHub if you have the required access, you can delete:
- an entire private package
- an entire public package, if there's not more than 5000 downloads of any version of the package
- a specific version of a private package
- a specific version of a public package, if the package version doesn't have more than 5,000 downloads
Note:
- You cannot delete a public package if any version of the package has more than 5,000 downloads. In this scenario, contact GitHub support for further assistance.
- When deleting public packages, be aware that you may break projects that depend on your package.
On GitHub, you can also restore an entire package or package version, if:
- You restore the package within 30 days of its deletion.
- The same package namespace is still available and not used for a new package.
Packages API support
GitHub Packages only supports authentication using a personal access token (classic). For more information, see "Creating a personal access token."
You can use the REST API to manage your packages. For more information, see the "GitHub Packages API."
Note: The ability for GitHub Actions workflows to delete and restore packages using the REST API is currently in public beta and subject to change.
With registries that support granular permissions, you can use a GITHUB_TOKEN
in a GitHub Actions workflow to delete or restore packages using the REST API. The token must have admin
permission to the package. If your workflow publishes a package, the admin
role is granted by default to the repository where the workflow is stored. For existing packages not published by a workflow, you need to grant the repository the admin
role to be able to use a GitHub Actions workflow to delete or restore packages using the REST API. For more information, see "Ensuring workflow access to your package."
For certain registries, you can use GraphQL to delete a version of a private package.
You cannot use the GitHub Packages GraphQL API with registries that support granular permissions. For the registries that only support repository-scoped permissions, and can be used with the GraphQL API, see "About permissions for GitHub Packages."
Required permissions to delete or restore a package
With registries that support granular permissions, you can choose to allow packages to be scoped to a user or an organization, or linked to a repository.
To delete a package that has granular permissions separate from a repository, such as container images stored at https://ghcr.io/OWNER/PACKAGE-NAME
or packages stored at https://npm.pkg.github.com/OWNER/PACKAGE-NAME
, you must have admin access to the package. For more information, see "About permissions for GitHub Packages."
For packages that inherit their access permissions from repositories, you can delete a package if you have admin permissions to the repository.
Some registries only support repository-scoped packages. For a list of these registries, see "About permissions for GitHub Packages."
Deleting a package version
Deleting a version of a repository-scoped package on GitHub
To delete a version of a repository-scoped package, you must have admin permissions to the repository that owns the package. For more information, see "Required permissions."
-
On GitHub.com, navigate to the main page of the repository.
-
To the right of the list of files, click Packages.
-
Search for and select your package.
-
In the top right of your package's landing page, click Package settings.
-
On the left, click Manage versions.
-
To the right of the version you want to delete, click and select Delete version.
-
To confirm deletion, type the package name and click I understand the consequences, delete this version.
Deleting a version of a repository-scoped package with GraphQL
For certain registries, you can use GraphQL to delete a version of a private package.
You cannot use the GitHub Packages GraphQL API with registries that support granular permissions. For the registries that only support repository-scoped permissions, and can be used with the GraphQL API, see "About permissions for GitHub Packages." For information on using the REST API instead, see the "GitHub Packages API."
Use the deletePackageVersion
mutation in the GraphQL API. You must use a personal access token (classic) with the read:packages
, delete:packages
, and repo
scopes. For more information about personal access tokens (classic), see "About GitHub Packages."
The following example demonstrates how to delete a package version, using a packageVersionId
of MDIyOlJlZ2lzdHJ5UGFja2FnZVZlcnNpb243MTExNg
.
curl -X POST \
-H "Accept: application/vnd.github.package-deletes-preview+json" \
-H "Authorization: bearer TOKEN" \
-d '{"query":"mutation { deletePackageVersion(input:{packageVersionId:\"MDIyOlJlZ2lzdHJ5UGFja2FnZVZlcnNpb243MTExNg==\"}) { success }}"}' \
HOSTNAME/graphql
To find all of the private packages you have published to GitHub Packages, along with the version IDs for the packages, you can use the packages
connection through the repository
object. You will need a personal access token (classic) with the read:packages
and repo
scopes. For more information, see the packages
connection or the PackageOwner
interface.
For more information about the deletePackageVersion
mutation, see "deletePackageVersion
."
You cannot directly delete an entire package using GraphQL, but if you delete every version of a package, the package will no longer show on GitHub.
Deleting a version of a user-scoped package on GitHub
To delete a specific version of a user-scoped package on GitHub, such as for a Docker image at ghcr.io
, use these steps. To delete an entire package, see "Deleting an entire user-scoped package on GitHub."
To review who can delete a package version, see "Required permissions."
- On GitHub, navigate to the main page of your personal account.
- In the top right corner of GitHub.com, click your profile photo, then click Your profile.
- On your profile page, in the top right, click Packages.
- Search for and select your package.
- In the top right of your package's landing page, click Package settings.
- On the left, click Manage versions.
- To the right of the version you want to delete, click and select Delete version.
- To confirm deletion, type the package name and click I understand the consequences, delete this version.
Deleting a version of an organization-scoped package on GitHub
To delete a specific version of an organization-scoped package on GitHub, such as for a Docker image at ghcr.io
, use these steps.
To delete an entire package, see "Deleting an entire organization-scoped package on GitHub."
To review who can delete a package version, see "Required permissions to delete or restore a package."
-
On GitHub, navigate to the main page of your organization.
-
Under your organization name, click Packages.
-
Search for and select your package.
-
In the top right of your package's landing page, click Package settings.
-
On the left, click Manage versions.
-
To the right of the version you want to delete, click and select Delete version.
-
To confirm deletion, type the package name and click I understand the consequences, delete this version.
Deleting an entire package
Deleting an entire repository-scoped package on GitHub
To delete an entire repository-scoped package, you must have admin permissions to the repository that owns the package. For more information, see "Required permissions."
-
On GitHub.com, navigate to the main page of the repository.
-
To the right of the list of files, click Packages.
-
Search for and select your package.
-
In the top right of your package's landing page, click Package settings.
-
Under "Danger Zone", click Delete this package.
-
To confirm, review the confirmation message, enter your package name, and click I understand, delete this package.
Deleting an entire user-scoped package on GitHub
To review who can delete a package, see "Required permissions."
- On GitHub, navigate to the main page of your personal account.
- In the top right corner of GitHub.com, click your profile photo, then click Your profile.
- On your profile page, in the top right, click Packages.
- Search for and select your package.
- In the top right of your package's landing page, click Package settings.
- On the left, click Options.
- Under "Danger zone", click Delete this package.
- To confirm deletion, type the package name and click I understand the consequences, delete this package.
Deleting an entire organization-scoped package on GitHub
To review who can delete a package, see "Required permissions."
-
On GitHub, navigate to the main page of your organization.
-
Under your organization name, click Packages.
-
Search for and select your package.
-
In the top right of your package's landing page, click Package settings.
-
On the left, click Options.
-
Under "Danger zone", click Delete this package.
-
To confirm deletion, type the package name and click I understand the consequences, delete this package.
Restoring packages
You can restore a deleted package or version if:
- You restore the package within 30 days of its deletion.
- The same package namespace and version is still available and not reused for a new package.
For example, if you have a deleted RubyGems package named octo-package
that was scoped to the repo octo-repo-owner/octo-repo
, then you can only restore the package if the package namespace rubygem.pkg.github.com/octo-repo-owner/octo-repo/octo-package
is still available, and 30 days have not yet passed.
To restore a deleted package, you must also meet one of these permission requirements:
- For repository-scoped packages: You have admin permissions to the repository that owns the deleted package.
- For user-account scoped packages: Your personal account owns the deleted package.
- For organization-scoped packages: You have admin permissions to the deleted package in the organization that owns the package.
For more information, see "Required permissions."
Once the package is restored, the package will use the same namespace it did before. If the same package namespace is not available, you will not be able to restore your package. In this scenario, to restore the deleted package, you must delete the new package that uses the deleted package's namespace first.
Restoring a package in an organization
You can restore a deleted package through your organization account settings, as long as the package was in a repository owned by the organization or had granular permissions and was scoped to your organization account.
To review who can restore a package in an organization, see "Required permissions."
-
On GitHub.com, navigate to the main page of the organization.
-
Under your organization name, click Settings.
-
On the left, click Packages.
-
Under "Deleted Packages", next to the package you want to restore, click Restore.
-
To confirm, type the name of the package and click I understand the consequences, restore this package.
Restoring a user-account scoped package
You can restore a deleted package through your personal account settings, if the package was in one of your repositories or scoped to your personal account. For more information, see "Required permissions."
-
In the upper-right corner of any page, click your profile photo, then click Settings.
-
On the left, click Packages.
-
Under "Deleted Packages", next to the package you want to restore, click Restore.
-
To confirm, type the name of the package and click I understand the consequences, restore this package.
Restoring a package version
You can restore a package version from your package's landing page. To review who can restore a package, see "Required permissions."
- Navigate to your package's landing page.
- On the right, click Package settings.
- On the left, click Manage versions.
- On the top right, use the "Versions" drop-down menu and select Deleted.
- Next to the deleted package version you want to restore, click Restore.
- To confirm, click I understand the consequences, restore this version.