List objects Stay organized with collections Save and categorize content based on your preferences.
This page shows you how to list theobjects stored in your Cloud Storagebuckets, which are ordered in the list lexicographically by name.
Before you begin
To get the permissions that you need to list objects, ask your administratorto grant you the Storage Object Viewer (roles/storage.objectViewer)IAM role for the bucket that contains the objects you want tolist. If you want to list objects withinmanaged folders, you can grantroles/storage.objectViewer on the managed folder that contains the objectsyou want to view instead of the bucket.
If you plan on using the Google Cloud console to perform the tasks on this page,ask your administrator to grant you the Viewer (roles/viewer) basic role inaddition to the Storage Object Viewer (roles/storage.objectViewer) role.
These roles contain the permissions required to list objects. To see the exactpermissions that are required, expand theRequired permissions section:
Required permissions
storage.objects.liststorage.buckets.list- This permission is only needed if you want to use the Google Cloud console to perform the tasks on this page.
You can also get these permissions with otherpredefined roles orcustom roles.
For information about granting roles for buckets, seeSet and manage IAM policies on buckets.
List the objects in a bucket
Console
- In the Google Cloud console, go to the Cloud StorageBuckets page.
In the bucket list, click the name of the bucket whose contents youwant to view.
Command line
Use thegcloud storage ls command:
gcloud storage ls gs://BUCKET_NAME
Where:
BUCKET_NAMEis the name of the bucket thatcontains the objects you want to list. For example,my-bucket.
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 objects in a bucket: The following sample lists objects with a given prefix: 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 objects in a bucket: The following sample lists objects with a given prefix: 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 objects in a bucket: The following sample lists objects with a given prefix: 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 objects in a bucket: The following sample lists objects with a given prefix: 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 objects in a bucket: The following sample lists objects with a given prefix: 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 objects in a bucket: The following sample lists objects with a given prefix: 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 objects in a bucket: The following sample lists objects with a given prefix: 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 objects in a bucket: The following sample lists objects with a given prefix:C++
namespacegcs=::google::cloud::storage;[](gcs::Clientclient,std::stringconst&bucket_name){for(auto&&object_metadata:client.ListObjects(bucket_name)){if(!object_metadata)throwstd::move(object_metadata).status();std::cout <<"bucket_name=" <<object_metadata->bucket() <<", object_name=" <<object_metadata->name() <<"\n";}}namespacegcs=::google::cloud::storage;[](gcs::Clientclient,std::stringconst&bucket_name,std::stringconst&bucket_prefix){for(auto&&object_metadata:client.ListObjects(bucket_name,gcs::Prefix(bucket_prefix))){if(!object_metadata)throwstd::move(object_metadata).status();std::cout <<"bucket_name=" <<object_metadata->bucket() <<", object_name=" <<object_metadata->name() <<"\n";}}C#
usingGoogle.Cloud.Storage.V1;usingSystem;usingSystem.Collections.Generic;publicclassListFilesSample{publicIEnumerable<Google.Apis.Storage.v1.Data.Object>ListFiles(stringbucketName="your-unique-bucket-name"){varstorage=StorageClient.Create();varstorageObjects=storage.ListObjects(bucketName);Console.WriteLine($"Files in bucket {bucketName}:");foreach(varstorageObjectinstorageObjects){Console.WriteLine(storageObject.Name);}returnstorageObjects;}}usingGoogle.Cloud.Storage.V1;usingSystem;usingSystem.Collections.Generic;publicclassListFilesWithPrefixSample{/// <summary>/// Prefixes and delimiters can be used to emulate directory listings./// Prefixes can be used to filter objects starting with prefix./// The delimiter argument can be used to restrict the results to only the/// objects in the given "directory". Without the delimiter, the entire tree/// under the prefix is returned./// For example, given these objects:/// a/1.txt/// a/b/2.txt////// If you just specify prefix="a/", you'll get back:/// a/1.txt/// a/b/2.txt////// However, if you specify prefix="a/" and delimiter="/", you'll get back:/// a/1.txt/// </summary>/// <param name="bucketName">The bucket to list the objects from.</param>/// <param name="prefix">The prefix to match. Only objects with names that start with this string will/// be returned. This parameter may be null or empty, in which case no filtering/// is performed.</param>/// <param name="delimiter">Used to list in "directory mode". Only objects whose names (aside from the prefix)/// do not contain the delimiter will be returned.</param>publicIEnumerable<Google.Apis.Storage.v1.Data.Object>ListFilesWithPrefix(stringbucketName="your-unique-bucket-name",stringprefix="your-prefix",stringdelimiter="your-delimiter"){varstorage=StorageClient.Create();varoptions=newListObjectsOptions{Delimiter=delimiter};varstorageObjects=storage.ListObjects(bucketName,prefix,options);Console.WriteLine($"Objects in bucket {bucketName} with prefix {prefix}:");foreach(varstorageObjectinstorageObjects){Console.WriteLine(storageObject.Name);}returnstorageObjects;}}Go
import("context""fmt""io""time""cloud.google.com/go/storage""google.golang.org/api/iterator")// listFiles lists objects within specified bucket.funclistFiles(wio.Writer,bucketstring)error{// bucket := "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*10)defercancel()it:=client.Bucket(bucket).Objects(ctx,nil)for{attrs,err:=it.Next()iferr==iterator.Done{break}iferr!=nil{returnfmt.Errorf("Bucket(%q).Objects: %w",bucket,err)}fmt.Fprintln(w,attrs.Name)}returnnil}import("context""fmt""io""time""cloud.google.com/go/storage""google.golang.org/api/iterator")// listFilesWithPrefix lists objects using prefix and delimeter.funclistFilesWithPrefix(wio.Writer,bucket,prefix,delimstring)error{// bucket := "bucket-name"// prefix := "/foo"// delim := "_"ctx:=context.Background()client,err:=storage.NewClient(ctx)iferr!=nil{returnfmt.Errorf("storage.NewClient: %w",err)}deferclient.Close()// Prefixes and delimiters can be used to emulate directory listings.// Prefixes can be used to filter objects starting with prefix.// The delimiter argument can be used to restrict the results to only the// objects in the given "directory". Without the delimiter, the entire tree// under the prefix is returned.//// For example, given these blobs:// /a/1.txt// /a/b/2.txt//// If you just specify prefix="a/", you'll get back:// /a/1.txt// /a/b/2.txt//// However, if you specify prefix="a/" and delim="/", you'll get back:// /a/1.txtctx,cancel:=context.WithTimeout(ctx,time.Second*10)defercancel()it:=client.Bucket(bucket).Objects(ctx,&storage.Query{Prefix:prefix,Delimiter:delim,})for{attrs,err:=it.Next()iferr==iterator.Done{break}iferr!=nil{returnfmt.Errorf("Bucket(%q).Objects(): %w",bucket,err)}fmt.Fprintln(w,attrs.Name)}returnnil}Java
importcom.google.api.gax.paging.Page;importcom.google.cloud.storage.Blob;importcom.google.cloud.storage.Storage;importcom.google.cloud.storage.StorageOptions;publicclassListObjects{publicstaticvoidlistObjects(StringprojectId,StringbucketName){// The ID of your GCP project// String projectId = "your-project-id";// The ID of your GCS bucket// String bucketName = "your-unique-bucket-name";Storagestorage=StorageOptions.newBuilder().setProjectId(projectId).build().getService();Page<Blob>blobs=storage.list(bucketName);for(Blobblob:blobs.iterateAll()){System.out.println(blob.getName());}}}importcom.google.api.gax.paging.Page;importcom.google.cloud.storage.Blob;importcom.google.cloud.storage.Storage;importcom.google.cloud.storage.StorageOptions;publicclassListObjectsWithPrefix{publicstaticvoidlistObjectsWithPrefix(StringprojectId,StringbucketName,StringdirectoryPrefix){// The ID of your GCP project// String projectId = "your-project-id";// The ID of your GCS bucket// String bucketName = "your-unique-bucket-name";// The directory prefix to search for// String directoryPrefix = "myDirectory/"Storagestorage=StorageOptions.newBuilder().setProjectId(projectId).build().getService();/** * Using the Storage.BlobListOption.currentDirectory() option here causes the results to display * in a "directory-like" mode, showing what objects are in the directory you've specified, as * well as what other directories exist in that directory. For example, given these blobs: * * <p>a/1.txt a/b/2.txt a/b/3.txt * * <p>If you specify prefix = "a/" and don't use Storage.BlobListOption.currentDirectory(), * you'll get back: * * <p>a/1.txt a/b/2.txt a/b/3.txt * * <p>However, if you specify prefix = "a/" and do use * Storage.BlobListOption.currentDirectory(), you'll get back: * * <p>a/1.txt a/b/ * * <p>Because a/1.txt is the only file in the a/ directory and a/b/ is a directory inside the * /a/ directory. */Page<Blob>blobs=storage.list(bucketName,Storage.BlobListOption.prefix(directoryPrefix),Storage.BlobListOption.currentDirectory());for(Blobblob:blobs.iterateAll()){System.out.println(blob.getName());}}}Node.js
/** * 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();asyncfunctionlistFiles(){// Lists files in the bucketconst[files]=awaitstorage.bucket(bucketName).getFiles();console.log('Files:');files.forEach(file=>{console.log(file.name);});}listFiles().catch(console.error);/** * TODO(developer): Uncomment the following lines before running the sample. */// The ID of your GCS bucket// const bucketName = 'your-unique-bucket-name';// The directory prefix to search for// const prefix = 'myDirectory/';// The delimiter to use// const delimiter = '/';// Imports the Google Cloud client libraryconst{Storage}=require('@google-cloud/storage');// Creates a clientconststorage=newStorage();asyncfunctionlistFilesByPrefix(){/** * This can be used to list all blobs in a "folder", e.g. "public/". * * The delimiter argument can be used to restrict the results to only the * "files" in the given "folder". Without the delimiter, the entire tree under * the prefix is returned. For example, given these blobs: * * /a/1.txt * /a/b/2.txt * * If you just specify prefix = 'a/', you'll get back: * * /a/1.txt * /a/b/2.txt * * However, if you specify prefix='a/' and delimiter='/', you'll get back: * * /a/1.txt */constoptions={prefix:prefix,};if(delimiter){options.delimiter=delimiter;}// Lists files in the bucket, filtered by a prefixconst[files]=awaitstorage.bucket(bucketName).getFiles(options);console.log('Files:');files.forEach(file=>{console.log(file.name);});}listFilesByPrefix().catch(console.error);PHP
use Google\Cloud\Storage\StorageClient;/** * List Cloud Storage bucket objects. * * @param string $bucketName The name of your Cloud Storage bucket. * (e.g. 'my-bucket') */function list_objects(string $bucketName): void{ $storage = new StorageClient(); $bucket = $storage->bucket($bucketName); foreach ($bucket->objects() as $object) { printf('Object: %s' . PHP_EOL, $object->name()); }}use Google\Cloud\Storage\StorageClient;/** * List Cloud Storage bucket objects with specified prefix. * * @param string $bucketName The name of your Cloud Storage bucket. * (e.g. 'my-bucket') * @param string $directoryPrefix the prefix to use in the list objects API call. * (e.g. 'myDirectory/') */function list_objects_with_prefix(string $bucketName, string $directoryPrefix): void{ $storage = new StorageClient(); $bucket = $storage->bucket($bucketName); $options = ['prefix' => $directoryPrefix]; foreach ($bucket->objects($options) as $object) { printf('Object: %s' . PHP_EOL, $object->name()); }}Python
fromgoogle.cloudimportstoragedeflist_blobs(bucket_name):"""Lists all the blobs in the bucket."""# bucket_name = "your-bucket-name"storage_client=storage.Client()# Note: Client.list_blobs requires at least package version 1.17.0.blobs=storage_client.list_blobs(bucket_name)# Note: The call returns a response only when the iterator is consumed.forblobinblobs:print(blob.name)fromgoogle.cloudimportstoragedeflist_blobs_with_prefix(bucket_name,prefix,delimiter=None):"""Lists all the blobs in the bucket that begin with the prefix. This can be used to list all blobs in a "folder", e.g. "public/". The delimiter argument can be used to restrict the results to only the "files" in the given "folder". Without the delimiter, the entire tree under the prefix is returned. For example, given these blobs: a/1.txt a/b/2.txt If you specify prefix ='a/', without a delimiter, you'll get back: a/1.txt a/b/2.txt However, if you specify prefix='a/' and delimiter='/', you'll get back only the file directly under 'a/': a/1.txt As part of the response, you'll also get back a blobs.prefixes entity that lists the "subfolders" under `a/`: a/b/ Note: If you only want to list prefixes a/b/ and don't want to iterate over blobs, you can do ``` for page in blobs.pages: print(page.prefixes) ``` """storage_client=storage.Client()# Note: Client.list_blobs requires at least package version 1.17.0.blobs=storage_client.list_blobs(bucket_name,prefix=prefix,delimiter=delimiter)# Note: The call returns a response only when the iterator is consumed.print("Blobs:")forblobinblobs:print(blob.name)ifdelimiter:print("Prefixes:")forprefixinblobs.prefixes:print(prefix)Ruby
deflist_filesbucket_name:# The ID of your GCS bucket# bucket_name = "your-unique-bucket-name"require"google/cloud/storage"storage=Google::Cloud::Storage.newbucket=storage.bucketbucket_namebucket.files.eachdo|file|putsfile.nameendenddeflist_files_with_prefixbucket_name:,prefix:,delimiter:nil# Lists all the files in the bucket that begin with the prefix.## This can be used to list all files in a "folder", e.g. "public/".## The delimiter argument can be used to restrict the results to only the# "files" in the given "folder". Without the delimiter, the entire tree under# the prefix is returned. For example, given these files:## a/1.txt# a/b/2.txt## If you just specify `prefix: "a"`, you will get back:## a/1.txt# a/b/2.txt## However, if you specify `prefix: "a"` and `delimiter: "/"`, you will get back:## a/1.txt# The ID of your GCS bucket# bucket_name = "your-unique-bucket-name"# The directory prefix to search for# prefix = "a"# The delimiter to be used to restrict the results# delimiter = "/"require"google/cloud/storage"storage=Google::Cloud::Storage.newbucket=storage.bucketbucket_namefiles=bucket.filesprefix:prefix,delimiter:delimiterfiles.eachdo|file|putsfile.nameendend
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 objects:curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o"
Where
BUCKET_NAMEis the name of the bucketwhose objects you want to list. For example,my-bucket.
XML API
Have gcloud CLIinstalled and initialized, which lets you generate an access token for the
Authorizationheader.Use
cURLto call theXML API with aGETBucket request:curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://storage.googleapis.com/BUCKET_NAME?list-type=2"
Where
BUCKET_NAMEis the name of the bucketwhose objects you want to list. For example,my-bucket.You can use a
prefix=PREFIXquery stringparameter to limit results to objects that have the specifiedprefix.
List the objects in a folder
Console
- In the Google Cloud console, go to the Cloud StorageBuckets page.
In the bucket list, click the name of the bucket that contains thefolder.
In theObjects tab of theBucket details page, click the name ofthe folder whose contents you want to view.
Command line
Use thegcloud storage ls command to list the objects in a folder:
gcloud storage ls gs://BUCKET_NAME/FOLDER_NAME
Where:
BUCKET_NAMEis the name of the bucket thatcontains the folder. For example,my-bucket.FOLDER_NAMEis the name of the folder thatcontains the objects you want to list. For example,my-folder.
REST APIs
JSON API
To list the objects in a folder, use alist objects requestwith theprefix anddelimiter parameters. When theprefixparameter is set, the list operation is scoped to only return objectsand folders under the prefix. When thedelimiter parameter is set,theprefixes[] list in the response populates with the names offolders under the specified prefix.
For example:
To list all objects in the folder
image/within thebucketmy-bucket, use the following URL:"https://storage.googleapis.com/storage/v1/b/my-bucket/o?prefix=image&delimiter=/".This could return the objects
my-bucket/image/cat.jpegandmy-bucket/image/dog.jpeg.To include objects in subfolders within
image/, remove thedelimiterparameter:"https://storage.googleapis.com/storage/v1/b/my-bucket/o?prefix=image".This could return the objects
my-bucket/image/cat.jpeg,my-bucket/image/dog.jpeg, andmy-bucket/image/dog/shiba.jpeg.
To use wildcards in your list objects request and match objects byglob expression, use thematchGlobparameter. For example,matchGlob=**.jpeg matches allobjects that end in.jpeg. When you usematchGlob, you must setdelimiter to/.
For example, use the following URL to match all objects within thefolderimage that end in.jpeg:"https://storage.googleapis.com/storage/v1/b/my-bucket/o?prefix=image&delimiter=/&matchGlob=**.jpeg"
For more details about using parameters to filter for objects, see theObjects list JSON API reference documentation.
Use case
Usingprefix to list the contents of a folder can be useful forwhen you only have the permission to list objects in the folder, but notthe whole bucket. For example, say you have the Storage Object Viewer(roles/storage.objectViewer) IAMrole for themanaged foldermy-bucket/my-managed-folder-a/, butnot for the managed foldermy-bucket/my-managed-folder-b/. To returnonly the objects inmy-managed-folder-a, you can specifyprefix=my-managed-folder-a/.
includeFoldersAsPrefixes parameter totrue and thedelimiterparameter to/.Filtering objects
When listing objects, you can use prefixes or suffixes in your list request tofilter objects by name. To use wildcards and filter objects byglob expression, use thematchGlob parameter (ormatch_glob, dependingon the client library).
Console
Seefiltering and sorting for information on how to filter and sortobjects in buckets or folders.
Command line
You can usewildcards in yourgcloud storage ls command tofilter objects by prefix or suffix. For example, the following commandonly lists objects in the bucketmy-bucket whose name begins withimage and ends with.png:
gcloud storage ls gs://my-bucket/image*.png
If the request is successful, the response looks similar to the following:
gs://my-bucket/image.pnggs://my-bucket/image-dog.pnggs://my-bucket/image-cat.png...
You can use double-star wildcards to match zero or more folder levels ina path. For example, the following command only lists objects whose nameends in.jpeg in any folder or subfolder within the bucketmy-bucket:
gcloud storage ls gs://my-bucket/**/*.jpeg
If the request is successful, the response looks similar to the following:
gs://my-bucket/puppy.jpeggs://my-bucket/pug.jpeggs://my-bucket/pets/dog.jpeg...
REST APIs
Seelist objects in folders for information on how to filter objectsby folder or object name prefix.
Filter objects by contexts
You can use a filter to show only objects that have the specifiedcontexts(preview) in the list response.
Command line
Use thegcloud alpha storage objects list command:
gcloud alpha storage objects list gs://BUCKET_NAME --metadata-filter='contexts."KEY"="VALUE"'
Where:
BUCKET_NAMEis the name of the bucket containingthe object whose context you want to filter by. For example,my-bucket.KEYis the context key attached to the object.VALUEis the value associated with the context key.
If successful, the response looks similar to the following example:
---bucket: my-bucketcontexts: Department: createTime: '2023-01-01T00:00:00.000000+00:00' type: CUSTOM updateTime: '2023-01-01T00:00:00.000000+00:00' value: HR DataClassification: createTime: '2023-01-01T00:00:00.000000+00:00' type: CUSTOM updateTime: '2023-01-01T00:00:00.000000+00:00' value: Confidentialname: employees.txt...
--format=contextsonly.Client libraries
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.Java
importcom.google.api.gax.paging.Page;importcom.google.cloud.storage.Blob;importcom.google.cloud.storage.Storage;importcom.google.cloud.storage.StorageOptions;publicclassListObjectContexts{publicstaticvoidlistObjectContexts(StringprojectId,StringbucketName,Stringkey)throwsException{// The ID of your GCP project// String projectId = "your-project-id";// The ID of your GCS bucket// String bucketName = "your-unique-bucket-name";// The context key you want to filter// String key = "your-context-key";try(Storagestorage=StorageOptions.newBuilder().setProjectId(projectId).build().getService()){/* * List any object that has a context with the specified key attached * String filter = "contexts.\"KEY\":*"; * * List any object that that does not have a context with the specified key attached * String filter = "NOT contexts.\"KEY\":*"; * * List any object that has a context with the specified key and value attached * String filter = "contexts.\"KEY\"=\"VALUE\""; * * List any object that does not have a context with the specified key and value attached * String filter = "NOT contexts.\"KEY\"=\"VALUE\""; */Stringfilter="contexts.\""+key+"\":*";System.out.println("Listing objects for bucket: "+bucketName+"with context key: "+key);Page<Blob>blobs=storage.list(bucketName,Storage.BlobListOption.filter(filter));for(Blobblob:blobs.iterateAll()){System.out.println(blob.getBlobId().toGsUtilUri());}}}}
REST APIs
JSON API
TheObject: list request shows an example of how to use thefilter query parameter:
curl -X GET \-H "Authorization: Bearer $(gcloud auth print-access-token)" \"https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/?filter=contexts.%22KEY%22%3D%22VALUE%22"
Where:
BUCKET_NAMEis the name of the bucketcontaining the object whose context you want to filter by. Forexample,my-bucket.KEYis the context key attached to the object.VALUEis the value associated with the context key.
Syntax
Cloud Storage supports the following syntax for the filter.
| Syntax | Description |
|---|---|
contexts."KEY":* | Match any object that has a context with the specified key attached. |
contexts."KEY"="VALUE" | Match any object that has a context with the specified key and value attached. |
OR
| Match any object that does not have a context with the specified key attached. |
OR
| Match any object that does not have a context with the specified key and value attached. |
Performance considerations when listing objects
The underlying structure of buckets withhierarchical namespace enabledinfluences the performance of the listing objects operation, when compared toflat namespace buckets. For more information, seeOptimize performance in buckets with hierarchical namespace enabled.
What's next
- Download an object from your bucket.
- View and edit object metadata.
- Delete objects from your 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.