Listing buckets Stay organized with collections Save and categorize content based on your preferences.
This page shows you how to list the Cloud Storagebuckets in a project,which are ordered in the list lexicographically by name.
Before you begin
To get the permissions that you need to list buckets, ask your administrator togrant you the Storage Admin (roles/storage.admin) IAM role orthe Viewer (roles/viewer) basic role on the project that contains the bucketsyou want to list.
For more informationabout granting roles for projects, seeManage access to projects.
The roles contain thestorage.buckets.list permission, which isrequired to list buckets. You can also get this permission withcustom roles.
List the buckets in a project
Console
- In the Google Cloud console, go to the Cloud StorageBuckets page.
Buckets that are part of the selected project appear in the list.
Optionally, usefiltering and sorting to limit and organize theresults in your list.
Command line
Note: Cloud Shell provisions a temporary virtual machine. If you wantto upload objects to Cloud Storage or download objects fromCloud Storage, use a local development environment.In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, aCloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
In your development environment, run the
gcloud storage lscommand:gcloud storage ls
The response looks like the following example:
gs://BUCKET_NAME1/ gs://BUCKET_NAME2/ gs://BUCKET_NAME3/ ...
Client libraries
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. The following sample lists all available buckets. If a location is temporarily unavailable, the response also includes the names of any buckets that can't be reached. The following sample lists all buckets. If a location is temporarily unavailable, the service returns an error. 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. The following sample lists all available buckets. If a location is temporarily unavailable, the response also includes the names of any buckets that can't be reached. The following sample lists all buckets. If a location is temporarily unavailable, the service returns an error. 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. The following sample lists all available buckets. If a location is temporarily unavailable, the response also includes the names of any buckets that can't be reached. The following sample lists all buckets. If a location is temporarily unavailable, the service returns an error. 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. The following sample lists all available buckets. If a location is temporarily unavailable, the response also includes the names of any buckets that can't be reached. The following sample lists all buckets. If a location is temporarily unavailable, the service returns an error. 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. The following sample lists all available buckets. If a location is temporarily unavailable, the response also includes the names of any buckets that can't be reached. The following sample lists all buckets. If a location is temporarily unavailable, the service returns an error. 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. The following sample lists all available buckets. If a location is temporarily unavailable, the response also includes the names of any buckets that can't be reached. The following sample lists all buckets. If a location is temporarily unavailable, the service returns an error. 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. The following sample lists all available buckets. If a location is temporarily unavailable, the response also includes the names of any buckets that can't be reached. The following sample lists all buckets. If a location is temporarily unavailable, the service returns an error. 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. The following sample lists all available buckets. If a location is temporarily unavailable, the response also includes the names of any buckets that can't be reached. The following sample lists all buckets. If a location is temporarily unavailable, the service returns an error.C++
namespacegcs=::google::cloud::storage;using::google::cloud::StatusOr;[](gcs::Clientclient){intcount=0;gcs::ListBucketsExtendedReaderbucket_list=client.ListBucketsExtended();for(auto&&result:bucket_list){if(!result)throwstd::move(result).status();for(autoconst&bucket_metadata:result->buckets){std::cout <<bucket_metadata.name() <<"\n";++count;}for(autoconst&unreachable:result->unreachable){std::cout <<"Unreachable location: " <<unreachable <<"\n";}}if(count==0){std::cout <<"No buckets in default project\n";}}namespacegcs=::google::cloud::storage;using::google::cloud::StatusOr;[](gcs::Clientclient){intcount=0;gcs::ListBucketsReaderbucket_list=client.ListBuckets();for(auto&&bucket_metadata:bucket_list){if(!bucket_metadata)throwstd::move(bucket_metadata).status();std::cout <<bucket_metadata->name() <<"\n";++count;}if(count==0){std::cout <<"No buckets in default project\n";}}C#
usingGoogle.Api.Gax;usingGoogle.Apis.Storage.v1.Data;usingGoogle.Cloud.Storage.V1;usingSystem;usingSystem.Collections.Generic;usingSystem.Linq;publicclassListBucketsWithPartialSuccessSample{/// <summary>/// Lists buckets, returning both the reachable buckets and the resource names of buckets from unreachable locations when specific regions are unreachable./// </summary>/// <param name="projectId">The ID of the project to list the buckets.</param>public(IReadOnlyList<Bucket>Reachable,IReadOnlyList<string>Unreachable)ListBucketsWithPartialSuccess(stringprojectId="your-project-id"){varstorage=StorageClient.Create();varpagedResult=storage.ListBuckets(projectId,options:newListBucketsOptions{ReturnPartialSuccess=true});varreachableBuckets=newList<Bucket>();varunreachableBuckets=newList<string>();foreach(varpageinpagedResult.AsRawResponses()){reachableBuckets.AddRange(page.Items??Enumerable.Empty<Bucket>());unreachableBuckets.AddRange(page.Unreachable??Enumerable.Empty<string>());}Console.WriteLine("Buckets:");foreach(varbucketinreachableBuckets){Console.WriteLine(bucket.Name);}if(unreachableBuckets.Any()){Console.WriteLine("The Resource Names of Buckets from Unreachable Locations:");foreach(varbucketinunreachableBuckets){Console.WriteLine(bucket);}}return(reachableBuckets,unreachableBuckets);}}usingGoogle.Apis.Storage.v1.Data;usingGoogle.Cloud.Storage.V1;usingSystem;usingSystem.Collections.Generic;publicclassListBucketsSample{publicIEnumerable<Bucket>ListBuckets(stringprojectId="your-project-id"){varstorage=StorageClient.Create();varbuckets=storage.ListBuckets(projectId);Console.WriteLine("Buckets:");foreach(varbucketinbuckets){Console.WriteLine(bucket.Name);}returnbuckets;}}Go
import("context""fmt""io""time""cloud.google.com/go/storage""google.golang.org/api/iterator")// listBucketsPartialSuccess lists buckets in the project. If ReturnPartialSuccess// is true, the iterator will return reachable buckets and a list of// unreachable bucket resource names.funclistBucketsPartialSuccess(wio.Writer,projectIDstring)error{// projectID := "my-project-id"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()it:=client.Buckets(ctx,projectID)// Enable returning unreachable buckets.it.ReturnPartialSuccess=truefmt.Fprintln(w,"Reachable buckets:")for{battrs,err:=it.Next()iferr==iterator.Done{break}iferr!=nil{// Errors here usually indicate a problem with the overall list operation// or connection, such as a network issue, rather than individual// buckets being unreachable. Unreachable buckets due to issues like// regional outages or permission issues are typically reported via the// Unreachable() method below.returnerr}fmt.Fprintf(w,"- %v\n",battrs.Name)}// Retrieve the list of buckets that were unreachable.unreachable:=it.Unreachable()iflen(unreachable) >0{fmt.Fprintln(w,"\nUnreachable buckets:")for_,r:=rangeunreachable{fmt.Fprintf(w,"- %v\n",r)}}else{fmt.Fprintln(w,"\nNo unreachable buckets.")}returnnil}import("context""fmt""io""time""cloud.google.com/go/storage""google.golang.org/api/iterator")// listBuckets lists buckets in the project.funclistBuckets(wio.Writer,projectIDstring)([]string,error){// projectID := "my-project-id"ctx:=context.Background()client,err:=storage.NewClient(ctx)iferr!=nil{returnnil,fmt.Errorf("storage.NewClient: %w",err)}deferclient.Close()ctx,cancel:=context.WithTimeout(ctx,time.Second*30)defercancel()varbuckets[]stringit:=client.Buckets(ctx,projectID)for{battrs,err:=it.Next()iferr==iterator.Done{break}iferr!=nil{returnnil,err}buckets=append(buckets,battrs.Name)fmt.Fprintf(w,"Bucket: %v\n",battrs.Name)}returnbuckets,nil}Java
importcom.google.api.gax.paging.Page;importcom.google.cloud.storage.Bucket;importcom.google.cloud.storage.Storage;importcom.google.cloud.storage.StorageOptions;publicclassListBucketsWithPartialSuccess{publicstaticvoidlistBucketsWithPartialSuccess(StringprojectId){// The ID of your GCP project// String projectId = "your-project-id";Storagestorage=StorageOptions.newBuilder().setProjectId(projectId).build().getService();Page<Bucket>buckets=storage.list(Storage.BucketListOption.returnPartialSuccess(true));// Retrieve the list of buckets that are unreachable due to issues like regional outages or// permission issuesSystem.out.println("Unreachable buckets: \n");for(Bucketbucket:buckets.iterateAll()){if(Boolean.TRUE.equals(bucket.isUnreachable())){System.out.println(bucket.getName());}}}}importcom.google.api.gax.paging.Page;importcom.google.cloud.storage.Bucket;importcom.google.cloud.storage.Storage;importcom.google.cloud.storage.StorageOptions;publicclassListBuckets{publicstaticvoidlistBuckets(StringprojectId){// The ID of your GCP project// String projectId = "your-project-id";Storagestorage=StorageOptions.newBuilder().setProjectId(projectId).build().getService();Page<Bucket>buckets=storage.list();for(Bucketbucket:buckets.iterateAll()){System.out.println(bucket.getName());}}}Node.js
// Imports the Google Cloud client libraryconst{Storage}=require('@google-cloud/storage');// Creates a clientconststorage=newStorage();asyncfunctionlistBucketsPartialSuccess(){constoption={returnPartialSuccess:true,maxResults:5,};const[buckets,nextQuery,apiResponse]=awaitstorage.getBuckets(option);if(nextQuery &&nextQuery.pageToken){console.log(`Next Page Token:${nextQuery.pageToken}`);}console.log('\nBuckets:');buckets.forEach(bucket=>{if(bucket.unreachable){console.log(`${bucket.name} (unreachable:${bucket.unreachable})`);}else{console.log(`${bucket.name}`);}});if(apiResponse.unreachable &&apiResponse.unreachable.length >0){console.log('\nUnreachable Buckets:');apiResponse.unreachable.forEach(item=>{console.log(item);});}}listBucketsPartialSuccess().catch(console.error);// Imports the Google Cloud client libraryconst{Storage}=require('@google-cloud/storage');// Creates a clientconststorage=newStorage();asyncfunctionlistBuckets(){const[buckets]=awaitstorage.getBuckets();console.log('Buckets:');buckets.forEach(bucket=>{console.log(bucket.name);});}listBuckets().catch(console.error);PHP
use Google\Cloud\Storage\StorageClient;/** * Retrieves a list of buckets while gracefully handling regional downtime. */function list_buckets_partial_success(): void{ $storage = new StorageClient(); $options = [ 'returnPartialSuccess' => true ]; $buckets = $storage->buckets($options); // Check for unreachable locations first // Note: unreachable() returns an array of strings for buckets in unavailable regions if ($unreachable = $buckets->unreachable()) { foreach ($unreachable as $location) { printf('Unreachable Bucket: %s' . PHP_EOL, $location); } } // Iterate through the buckets that were successfully retrieved foreach ($buckets as $bucket) { printf('Bucket: %s' . PHP_EOL, $bucket->name()); }}use Google\Cloud\Storage\StorageClient;/** * List all Cloud Storage buckets for the current project. */function list_buckets(): void{ $storage = new StorageClient(); foreach ($storage->buckets() as $bucket) { printf('Bucket: %s' . PHP_EOL, $bucket->name()); }}Python
fromgoogle.cloudimportstoragedeflist_buckets_with_partial_success():"""Lists buckets and includes unreachable buckets in the response."""storage_client=storage.Client()buckets_iterator=storage_client.list_buckets(return_partial_success=True)forpageinbuckets_iterator.pages:ifpage.unreachable:print("Unreachable locations in this page:")forlocationinpage.unreachable:print(location)print("Reachable buckets in this page:")forbucketinpage:print(bucket.name)fromgoogle.cloudimportstoragedeflist_buckets():"""Lists all buckets."""storage_client=storage.Client()buckets=storage_client.list_buckets()forbucketinbuckets:print(bucket.name)Ruby
# Demonstrates listing Google Cloud Storage buckets with support for partial success.## This method initializes a Google Cloud Storage client and requests a list of buckets.# When `return_partial_success` is true, the API will return available buckets# and a list of any buckets that were unreachable.## @param return_partial_success_flag [Boolean] Whether to allow partial success from the API.# - true: returns the available buckets and populates `unreachable` with bucket names if any.# - false: throws an error if any buckets are unreachable.deflist_buckets_with_partial_successreturn_partial_success_flag:require"google/cloud/storage"storage=Google::Cloud::Storage.newbucket_list=storage.bucketsreturn_partial_success:return_partial_success_flagputs"Reachable buckets:"# limiting the bucket count to be printed to 10 for brevitybucket_list.take(10).eachdo|bucket|putsbucket.nameendifbucket_list.unreachableputs"\nUnreachable buckets:"# limiting the bucket count to be printed to 10 for brevitybucket_list.unreachable.take(10).eachdo|unreachable_bucket_name|putsunreachable_bucket_nameendendend
REST APIs
JSON API
Have gcloud CLIinstalled and initialized, which lets you generate an access token for the
Authorizationheader.Use
cURLto call theJSON API with arequest to list buckets:curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://storage.googleapis.com/storage/v1/b?project=PROJECT_IDENTIFIER&returnPartialSuccess=RETURN_PARTIAL_SUCCESS_BOOLEAN"
Replace the following:
PROJECT_IDENTIFIER: the ID or numberof the project containing the buckets you want to list. Forexample,my-project.RETURN_PARTIAL_SUCCESS_BOOLEAN: set thisvalue totrueif you want to return a list of bucketseven when some buckets can't be reached because a location istemporarily unavailable. If set tofalse, the request returns alist of buckets only if all locations can be reached, otherwiseit returns an error. The default isfalse.
XML API
Have gcloud CLIinstalled and initialized, which lets you generate an access token for the
Authorizationheader.Use
cURLto call theXML API with aGETService request:curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "x-goog-project-id:PROJECT_ID" \ "https://storage.googleapis.com"
Replace
PROJECT_IDwith the ID of the projectcontaining the buckets you want to list. For example,my-project.
What's next
- Get information about a bucket's size.
- List the objects in a bucket.
- Move or rename a bucket.
- Delete a bucket.
- Learn how topaginate results.
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-19 UTC.