This page describes how to list and restore a soft-deleted bucket.
Overview
After a bucket is soft-deleted, it's retained by Cloud Storage until its
hard delete time, and cannot be modified while in a soft-deleted state. The hard
delete time is at least as long as the latest hard delete time of the bucket's
objects. After the hard delete time has elapsed, Cloud Storage permanently
deletes the bucket. When you restore a soft-deleted bucket, it is returned to a
live state, and objects that were in the bucket at the time of deletion can also
be restored.
Considerations
To protect against malicious deletion, a soft-deleted bucket cannot
be permanently deleted until the bucket has been retained for its full
soft delete retention duration.
Once a bucket is a soft-deleted, you must restore the bucket before you
can list or restore the soft-deleted objects in it.
To restore a soft-deleted bucket, you must have the bucket's
generation number. To retrieve a soft-deleted bucket's generation number,
see List soft-deleted buckets.
A soft-deleted bucket can only be restored if there is no
live bucket with the same name. If you or anyone else creates a bucket
with the same name as a soft-deleted bucket, you cannot restore the
soft-deleted bucket until the new bucket is deleted.
Bucket restore operations don't restore the soft-deleted objects that were
in the bucket at the time of deletion. To restore soft-deleted objects after
the soft-deleted bucket has been restored, you'll need to perform an object
restore operation.
Tag bindings might not be recovered when you restore a soft-deleted bucket
with tags. To avoid data loss, when you restore a soft-deleted bucket with
tag bindings, we recommend checking to ensure the bucket's tag bindings were
recovered. If the bucket's tag bindings weren't recovered, you'll need to
manually bind the unrecovered tags to the bucket.
Required permissions
To get the permissions that
you need to restore soft-deleted buckets,
ask your administrator to grant you the
Storage Admin (roles/storage.admin)
IAM role on the Cloud Storage project.
This predefined role contains
the permissions required to restore soft-deleted buckets. To see the exact permissions that are
required, expand the Required permissions section:
Required permissions
The following permissions are required to restore soft-deleted buckets:
storage.buckets.list
storage.buckets.restore
List soft-deleted buckets
You can perform list operations to retrieve your soft-deleted buckets'
metadata.
Use the following instructions to list all soft-deleted buckets in your project:
Command line
To list all soft-deleted buckets, use the
gcloud storage ls command:
BUCKET_NAME: the name of the soft-deleted
bucket you want to restore.
GENERATION_NUMBER: the permanent, unique
generation number of the soft-deleted bucket you want to restore.
To get your bucket's generation number, see
List soft-deleted buckets.
BUCKET_NAME is the name of the bucket
you want to restore. For example, my-bucket.
GENERATION_NUMBER is the permanent,
unique generation number of the soft-deleted bucket you want
to restore. To get your bucket's generation number, see
List soft-deleted buckets.
Cloud Storage restores the soft-deleted bucket to a live state. Note that
restoring the bucket doesn't restore the objects that were in the bucket at the
time of soft deletion. To restore the soft-deleted objects that were in the
bucket at the time of deletion, see Restore a soft-deleted object.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-23 UTC."],[],[],null,["# Use soft-deleted buckets\n\n[Soft delete feature overview](/storage/docs/soft-delete)\n\nThis page describes how to list and restore a soft-deleted bucket.\n\nOverview\n--------\n\nAfter a bucket is soft-deleted, it's retained by Cloud Storage until its\nhard delete time, and cannot be modified while in a soft-deleted state. The hard\ndelete time is at least as long as the latest hard delete time of the bucket's\nobjects. After the hard delete time has elapsed, Cloud Storage permanently\ndeletes the bucket. When you restore a soft-deleted bucket, it is returned to a\nlive state, and objects that were in the bucket at the time of deletion can also\nbe restored.\n\nConsiderations\n--------------\n\n- To protect against malicious deletion, a soft-deleted bucket cannot\n be permanently deleted until the bucket has been retained for its full\n soft delete retention duration.\n\n- Once a bucket is a soft-deleted, you must restore the bucket before you\n can list or restore the soft-deleted objects in it.\n\n- To restore a soft-deleted bucket, you must have the bucket's\n generation number. To retrieve a soft-deleted bucket's generation number,\n see [List soft-deleted buckets](#list-soft-deleted-buckets).\n\n- A soft-deleted bucket can only be restored if there is no\n live bucket with the same name. If you or anyone else creates a bucket\n with the same name as a soft-deleted bucket, you cannot restore the\n soft-deleted bucket until the new bucket is deleted.\n\n- Bucket restore operations don't restore the soft-deleted objects that were\n in the bucket at the time of deletion. To restore soft-deleted objects after\n the soft-deleted bucket has been restored, you'll need to perform an object\n restore operation.\n\n- Tag bindings might not be recovered when you restore a soft-deleted bucket\n with tags. To avoid data loss, when you restore a soft-deleted bucket with\n tag bindings, we recommend checking to ensure the bucket's tag bindings were\n recovered. If the bucket's tag bindings weren't recovered, you'll need to\n [manually bind the unrecovered tags to the bucket](/resource-manager/docs/tags/tags-creating-and-managing#attaching).\n\nRequired permissions\n--------------------\n\n\nTo get the permissions that\nyou need to restore soft-deleted buckets,\n\nask your administrator to grant you the\n\n\n[Storage Admin](/iam/docs/roles-permissions/storage#storage.admin) (`roles/storage.admin`)\nIAM role on the Cloud Storage project.\n\n\nThis predefined role contains\n\nthe permissions required to restore soft-deleted buckets. To see the exact permissions that are\nrequired, expand the **Required permissions** section:\n\n\n#### Required permissions\n\nThe following permissions are required to restore soft-deleted buckets:\n\n- `storage.buckets.list`\n- `storage.buckets.restore`\n\nList soft-deleted buckets\n-------------------------\n\nYou can perform list operations to retrieve your soft-deleted buckets'\nmetadata.\n| **Note:** A bucket cannot be listed if its hard delete time has elapsed.\n\nUse the following instructions to list all soft-deleted buckets in your project: \n\n### Command line\n\nTo list all soft-deleted buckets, use the\n[`gcloud storage ls`](/sdk/gcloud/reference/storage/buckets/list) command: \n\n```\ngcloud storage ls --buckets --soft-deleted --full\n```\n\n### REST APIs\n\n### JSON API\n\n1. Have gcloud CLI [installed and initialized](/sdk/docs/install), which lets\n you generate an access token for the `Authorization` header.\n\n\n2.\n\n Use [`cURL`](http://curl.haxx.se/) to call the [JSON API](/storage/docs/json_api) with a\n [`GET` Bucket](/storage/docs/json_api/v1/buckets/list) request:\n\n```\ncurl -X GET \\\n -H \"Authorization: Bearer $(gcloud auth print-access-token)\" \\\n -H \"Content-Type: application/json\" \\\n \"https://storage.googleapis.com/storage/v1/b?softDeleted=true\"\n```\n\nRestore a soft-deleted bucket\n-----------------------------\n\nUse the following instructions to restore a soft-deleted bucket: \n\n### Command line\n\nTo restore a soft-deleted bucket, use the [`gcloud storage restore`](/sdk/gcloud/reference/storage/restore)\ncommand: \n\n```\n gcloud storage restore gs://BUCKET_NAME#GENERATION_NUMBER\n```\n\nReplace the following:\n\n- \u003cvar translate=\"no\"\u003eBUCKET_NAME\u003c/var\u003e: the name of the soft-deleted\n bucket you want to restore.\n\n- \u003cvar translate=\"no\"\u003eGENERATION_NUMBER\u003c/var\u003e: the permanent, unique\n generation number of the soft-deleted bucket you want to restore.\n To get your bucket's generation number, see\n [List soft-deleted buckets](#list-soft-deleted-buckets).\n\n### REST APIs\n\n### JSON API\n\n1. Have gcloud CLI [installed and initialized](/sdk/docs/install), which lets\n you generate an access token for the `Authorization` header.\n\n\n2.\n\n Use [`cURL`](http://curl.haxx.se/) to call the [JSON API](/storage/docs/json_api) with a\n [`POST` Bucket](/storage/docs/json_api/v1/buckets/restore) request: \n\n ```\n curl -X POST \\\n -H \"Authorization: Bearer $(gcloud auth print-access-token)\" \\\n -H \"Content-Type: application/json\" \\\n \"https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/restore?generation=GENERATION_NUMBER\n ```\n\n Where:\n - \u003cvar translate=\"no\"\u003eBUCKET_NAME\u003c/var\u003e is the name of the bucket\n you want to restore. For example, `my-bucket`.\n\n - \u003cvar translate=\"no\"\u003eGENERATION_NUMBER\u003c/var\u003e is the permanent,\n unique generation number of the soft-deleted bucket you want\n to restore. To get your bucket's generation number, see\n [List soft-deleted buckets](#list-soft-deleted-buckets).\n\nCloud Storage restores the soft-deleted bucket to a live state. Note that\nrestoring the bucket doesn't restore the objects that were in the bucket at the\ntime of soft deletion. To restore the soft-deleted objects that were in the\nbucket at the time of deletion, see [Restore a soft-deleted object](/storage/docs/use-soft-deleted-objects#restore).\n\nWhat's next\n-----------\n\n- [Restore soft-deleted objects in your bucket](/storage/docs/use-soft-deleted-objects#restore)."]]
