List objectsStay organized with collectionsSave and categorize content based on your preferences.
This page shows you how to list objects stored in your Cloud Storage buckets.Objectsare ordered in the list lexicographically by name.
Before you begin
To get the permissions that you need to list objects, ask your administrator
to grant you the Storage Object Viewer (roles/storage.objectViewer)
IAM role for the bucket that contains the objects you want to
list. If you want to list objects withinmanaged folders, you can grantroles/storage.objectVieweron the managed folder that contains the objects
you 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 in
addition to the Storage Object Viewer (roles/storage.objectViewer) role.
These roles contain the permissions required to list objects. To see the exact
permissions that are required, expand theRequired permissionssection:
Required permissions
storage.objects.list
storage.buckets.list
This permission is only needed if you want to use the Google Cloud console
to perform the tasks on this page.
The following sample lists all objects in a bucket:
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;}}
The following sample lists objects with a given prefix:
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;}}
The following sample lists objects with a given prefix:
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}
The following sample lists all objects in a bucket:
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());}}}
The following sample lists objects with a given prefix:
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());}}}
The following sample lists all objects in a bucket:
/*** 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);
The following sample lists objects with a given prefix:
/*** 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);
The following sample lists all objects in a bucket:
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());}}
The following sample lists objects with a given prefix:
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());}}
The following sample lists all objects in a bucket:
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)
The following sample lists objects with a given prefix:
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 underthe prefix is returned. For example, given these blobs:a/1.txta/b/2.txtIf you specify prefix ='a/', without a delimiter, you'll get back:a/1.txta/b/2.txtHowever, if you specify prefix='a/' and delimiter='/', you'll get backonly the file directly under 'a/':a/1.txtAs part of the response, you'll also get back a blobs.prefixes entitythat lists the "subfolders" under `a/`:a/b/Note: If you only want to list prefixes a/b/ and don't want to iterate overblobs, 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)
The following sample lists all objects in a bucket:
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.nameendend
The following sample lists objects with a given prefix:
deflist_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
BUCKET_NAMEis the name of the bucket that
contains the folder. For example,my-bucket.
FOLDER_NAMEis the name of the folder that
contains 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 theprefixanddelimiterparameters. When theprefixparameter is set, the list operation is scoped to only return objects
and folders under the prefix. When thedelimiterparameter is set,
theprefixes[]list in the response populates with the names of
folders under the specified prefix.
For example:
To list all objects in the folderimage/within the
bucketmy-bucket, use the following URL:"https://storage.googleapis.com/storage/v1/b/my-bucket/o?prefix=image&delimiter=/".
This could return the objectsmy-bucket/image/cat.jpegandmy-bucket/image/dog.jpeg.
To include objects in subfolders withinimage/, remove thedelimiterparameter:"https://storage.googleapis.com/storage/v1/b/my-bucket/o?prefix=image".
This could return the objectsmy-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=**.jpegmatches all
objects that end in.jpeg. When you usematchGlob, you must setdelimiterto/.
For example, use the following URL to match all objects within the
folderimagethat end in.jpeg:"https://storage.googleapis.com/storage/v1/b/my-bucket/o?prefix=image&delimiter=/&matchGlob=**.jpeg"
Usingprefixto list the contents of a folder can be useful for
when you only have the permission to list objects in the folder, but not
the whole bucket. For example, say you have the Storage Object Viewer
(roles/storage.objectViewer) IAM
role for themanaged foldermy-bucket/my-managed-folder-a/, but
not for the managed foldermy-bucket/my-managed-folder-b/. To return
only the objects inmy-managed-folder-a, you can specifyprefix=my-managed-folder-a/.
Filtering objects
When listing objects, you can use prefixes or suffixes in your list request to
filter objects by name. To use wildcards and filter objects byglob expression, use thematchGlobparameter (ormatch_glob, depending
on the client library).
Console
Seefiltering and sortingfor information on how to filter and sort
objects in buckets or folders.
Command line
You can usewildcardsin yourgcloud storage lscommand to
filter objects by prefix or suffix. For example, the following command
only lists objects in the bucketmy-bucketwhose name begins withimageand ends with.png:
gcloud storage ls gs://my-bucket/image*.png
If the request is successful, the response looks similar to the following:
You can use double-star wildcards to match zero or more folder levels in
a path. For example, the following command only lists objects whose name
ends in.jpegin 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:
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: listrequest shows an example of how to use thefilterquery parameter to filter objects by context.
[[["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 2026-04-06 UTC."],[],[]]
