Delete buckets

This page shows you how to delete Cloud Storagebuckets.

If you delete a bucket that hassoft delete enabled,you can restore the bucket or individual objects from the bucket during theretention duration specified in the soft delete policy. Managed folderscannot be recovered, even if the bucket has soft delete enabled.

Warning: Once a bucket is deleted, anyone can reuse the bucket's namefor a new bucket and potentially receive data or requests intended for theoriginal deleted bucket. To learn how to mitigate this risk, seeBucket name considerations. Note that a soft-deleted bucket cannot berestored if its name becomes reused.

Before you begin

In order to get the required permissions for deleting a Cloud Storagebucket, ask your administrator to grant you the Storage Admin(roles/storage.admin) IAM role on the bucket.

This predefined role contains the permissions required to delete a bucket.To see the exact permissions that are required, expand theRequired permissions section:

Required permissions

  • storage.buckets.delete
  • storage.buckets.list
    • This permission is only required when deleting buckets using the Google Cloud console.
  • storage.objects.delete
    • This permission is only required if objects exist within the bucket you want to delete.
  • storage.objects.list
    • This permission is only required for deleting buckets using the Google Cloud console or the Google Cloud CLI.

You might also be able to get these permissions with othercustom roles orpredefined roles.

For instructions on granting roles for buckets, seeSet and manage IAM policies on buckets.

Delete a bucket

Console

When you delete a bucket using the Google Cloud console, resources withinthe bucket are also deleted, such as objects, managed folders, and cachescreated with Anywhere Cache.

  1. In the Google Cloud console, go to the Cloud StorageBuckets page.

    Go to Buckets

  2. Select the checkbox of the bucket you want to delete.

  3. ClickDelete.

  4. In the overlay window that appears, confirm you want to delete thebucket and its contents.

  5. ClickDelete.

Note: If you have a large number of objects in your buckets, the deleteoperation may take longer than usual to complete.

To learn how to get detailed error information about failed Cloud Storage operations in the Google Cloud console, seeTroubleshooting.

Command line

To delete the bucket, along with all the contents within the bucket,use theGoogle Cloud CLI commandgcloud storage rm withthe--recursive flag:

gcloud storage rm --recursive gs://BUCKET_NAME

WhereBUCKET_NAME is the name of the bucket to delete. For example,my-bucket.

If successful, the response looks like the following example:

Removing gs://my-bucket/...

If you want to avoid accidentally deleting objects or managed folders,use thegcloud storage buckets delete command, which only deletes abucket if the bucket is empty.

Note: If you need to delete a large number of objects in yourbuckets, avoid using Google Cloud CLI, as the operation takes a long timeto complete. Instead, use one of the following options:

For more information about protecting your data from accidental deletion, seeOptions for controlling data lifecycles.

Client libraries

Note: When you use client libraries, your bucket must be empty before youcan delete it. Some client libraries, like the Python client library,provide a force delete flag or function.

C++

For more information, see theCloud StorageC++ API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

namespacegcs=::google::cloud::storage;[](gcs::Clientclient,std::stringconst&bucket_name){google::cloud::Statusstatus=client.DeleteBucket(bucket_name);if(!status.ok())throwstd::runtime_error(status.message());std::cout <<"The bucket " <<bucket_name <<" was deleted successfully.\n";}

C#

For more information, see theCloud StorageC# API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

usingGoogle.Cloud.Storage.V1;usingSystem;publicclassDeleteBucketSample{publicvoidDeleteBucket(stringbucketName="your-unique-bucket-name"){varstorage=StorageClient.Create();storage.DeleteBucket(bucketName);Console.WriteLine($"The bucket {bucketName} was deleted.");}}

Go

For more information, see theCloud StorageGo API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

import("context""fmt""io""time""cloud.google.com/go/storage")// deleteBucket deletes the bucket.funcdeleteBucket(wio.Writer,bucketNamestring)error{// bucketName := "bucket-name"ctx:=context.Background()client,err:=storage.NewClient(ctx)iferr!=nil{returnfmt.Errorf("storage.NewClient: %w",err)}deferclient.Close()ctx,cancel:=context.WithTimeout(ctx,time.Second*30)defercancel()bucket:=client.Bucket(bucketName)iferr:=bucket.Delete(ctx);err!=nil{returnfmt.Errorf("Bucket(%q).Delete: %w",bucketName,err)}fmt.Fprintf(w,"Bucket %v deleted\n",bucketName)returnnil}

Java

For more information, see theCloud StorageJava API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

importcom.google.cloud.storage.Bucket;importcom.google.cloud.storage.Storage;importcom.google.cloud.storage.StorageOptions;publicclassDeleteBucket{publicstaticvoiddeleteBucket(StringprojectId,StringbucketName){// The ID of your GCP project// String projectId = "your-project-id";// The ID of the bucket to delete// String bucketName = "your-unique-bucket-name";Storagestorage=StorageOptions.newBuilder().setProjectId(projectId).build().getService();Bucketbucket=storage.get(bucketName);bucket.delete();System.out.println("Bucket "+bucket.getName()+" was deleted");}}

Node.js

For more information, see theCloud StorageNode.js API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

/** * TODO(developer): Uncomment the following lines before running the sample. */// The ID of your GCS bucket// const bucketName = 'your-unique-bucket-name';// Imports the Google Cloud client libraryconst{Storage}=require('@google-cloud/storage');// Creates a clientconststorage=newStorage();asyncfunctiondeleteBucket(){awaitstorage.bucket(bucketName).delete();console.log(`Bucket${bucketName} deleted`);}deleteBucket().catch(console.error);

PHP

For more information, see theCloud StoragePHP API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

use Google\Cloud\Storage\StorageClient;/** * Delete a Cloud Storage Bucket. * * @param string $bucketName The name of your Cloud Storage bucket. *        (e.g. 'my-bucket') */function delete_bucket(string $bucketName): void{    $storage = new StorageClient();    $bucket = $storage->bucket($bucketName);    $bucket->delete();    printf('Bucket deleted: %s' . PHP_EOL, $bucket->name());}

Python

For more information, see theCloud StoragePython API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

fromgoogle.cloudimportstoragedefdelete_bucket(bucket_name):"""Deletes a bucket. The bucket must be empty."""# bucket_name = "your-bucket-name"storage_client=storage.Client()bucket=storage_client.get_bucket(bucket_name)bucket.delete()print(f"Bucket{bucket.name} deleted")

Ruby

For more information, see theCloud StorageRuby API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

defdelete_bucketbucket_name:# The ID of your GCS bucket# bucket_name = "your-unique-bucket-name"require"google/cloud/storage"storage=Google::Cloud::Storage.newbucket=storage.bucketbucket_name,skip_lookup:truebucket.deleteputs"Deleted bucket:#{bucket.name}"end

REST APIs

JSON API

Note: When you use the JSON API, your bucket must be empty before youcan delete it.

  1. Have gcloud CLIinstalled and initialized, which lets you generate an access token for theAuthorization header.

  2. UsecURL to call theJSON API with aDELETE Bucket request:

    curl -X DELETE -H "Authorization: Bearer $(gcloud auth print-access-token)" \  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME"

    WhereBUCKET_NAME is the name of the bucketto delete. For example,my-bucket.

If successful, the response contains a 204 status code.

XML API

Note: When you use the XML API, your bucket must be empty before you candelete it.

  1. Have gcloud CLIinstalled and initialized, which lets you generate an access token for theAuthorization header.

  2. UsecURL to call theXML API with aDELETE Bucket request:

    curl -X DELETE -H "Authorization: Bearer $(gcloud auth print-access-token)" \  "https://storage.googleapis.com/BUCKET_NAME"

    WhereBUCKET_NAME is the name of the bucketto delete. For example,my-bucket.

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-18 UTC.