Delete buckets

This page shows you how to delete Cloud Storage buckets.

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

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

Before you begin

In order to get the required permissions for deleting a Cloud Storage bucket, 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 the Required 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 other custom roles or predefined roles.

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

Delete a bucket

Console

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

1. In the Google Cloud console, go to the Cloud Storage Buckets page.
   

   Go to Buckets

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

3. Click Delete.

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

5. Click Delete.

Note: If you have a large number of objects in your buckets, the delete operation 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, see Troubleshooting.

Command line

To delete the bucket, along with all the contents within the bucket, use the Google Cloud CLI command gcloud storage rm with the --recursive flag:

gcloud storage rm --recursive gs://BUCKET_NAME

Where BUCKET_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 the gcloud storage buckets delete command, which only deletes a bucket if the bucket is empty.

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

• Use the Google Cloud console.
• Create a storage batch operations job.
• Configure Object Lifecycle Management.

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

Client libraries

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

C++

For more information, see the Cloud Storage C++ API reference documentation.

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

namespace gcs = ::google::cloud::storage;
[](gcs::Client client, std::string const& bucket_name) {
  google::cloud::Status status = client.DeleteBucket(bucket_name);
  if (!status.ok()) throw std::runtime_error(status.message());

  std::cout << "The bucket " << bucket_name << " was deleted successfully.\n";
}

C#

For more information, see the Cloud Storage C# API reference documentation.

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

using Google.Cloud.Storage.V1;
using System;

public class DeleteBucketSample
{
    public void DeleteBucket(string bucketName = "your-unique-bucket-name")
    {
        var storage = StorageClient.Create();
        storage.DeleteBucket(bucketName);
        Console.WriteLine($"The bucket {bucketName} was deleted.");
    }
}

Go

For more information, see the Cloud Storage Go API reference documentation.

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

import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/storage"
)

// deleteBucket deletes the bucket.
func deleteBucket(w io.Writer, bucketName string) error {
	// bucketName := "bucket-name"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %w", err)
	}
	defer client.Close()

	ctx, cancel := context.WithTimeout(ctx, time.Second*30)
	defer cancel()

	bucket := client.Bucket(bucketName)
	if err := bucket.Delete(ctx); err != nil {
		return fmt.Errorf("Bucket(%q).Delete: %w", bucketName, err)
	}
	fmt.Fprintf(w, "Bucket %v deleted\n", bucketName)
	return nil
}

Java

For more information, see the Cloud Storage Java API reference documentation.

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

import com.google.cloud.storage.Bucket;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

public class DeleteBucket {
  public static void deleteBucket(String projectId, String bucketName) {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID of the bucket to delete
    // String bucketName = "your-unique-bucket-name";

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    Bucket bucket = storage.get(bucketName);
    bucket.delete();

    System.out.println("Bucket " + bucket.getName() + " was deleted");
  }
}

Node.js

For more information, see the Cloud Storage Node.js API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set 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 library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

async function deleteBucket() {
  await storage.bucket(bucketName).delete();
  console.log(`Bucket ${bucketName} deleted`);
}

deleteBucket().catch(console.error);

PHP

For more information, see the Cloud Storage PHP API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set 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 the Cloud Storage Python API reference documentation.

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

from google.cloud import storage


def delete_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 the Cloud Storage Ruby API reference documentation.

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

def delete_bucket bucket_name:
  # The ID of your GCS bucket
  # bucket_name = "your-unique-bucket-name"

  require "google/cloud/storage"

  storage = Google::Cloud::Storage.new
  bucket  = storage.bucket bucket_name, skip_lookup: true

  bucket.delete

  puts "Deleted bucket: #{bucket.name}"
end

REST APIs

JSON API

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

1. Have gcloud CLI installed and initialized, which lets you generate an access token for the Authorization header.

2. Use cURL to call the JSON API with a DELETE Bucket request:

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

   Where BUCKET_NAME is the name of the bucket to 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 can delete it.

1. Have gcloud CLI installed and initialized, which lets you generate an access token for the Authorization header.

2. Use cURL to call the XML API with a DELETE Bucket request:

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

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

What's next

• Create a bucket.
• Move or rename a bucket.
• List objects in a bucket.
• Delete an object.
• Restore a soft-deleted bucket.