Create and manage folders (original) (raw)

Skip to main content

• Technology areas

  • Overview
  • Guides
  • Reference
  • Samples
  • Resources

• Cross-product tools

• Console

• Discover

• Product overview

• Storage Intelligence overview

• Get started

• Terraform support for Cloud Storage

• Configure and manage Storage Intelligence

• Create buckets

• Create a bucket

• Domain-named bucket verification

• Access and manage buckets

• List buckets

• Change the default storage class of a bucket

• Move and rename buckets

• Delete buckets

• Upload and download objects

• About objects

• Overview of uploads and downloads

• Access and manage objects

• List objects

• Copy, rename, and move objects

• Change an object's storage class

• Tools to access and manage objects using a directory structure

• Object transcoding

• Delete objects

• Get insights on your stored data

• Analyze stored data with Gemini Cloud Assist

• Cache objects

• About caching

• Control data lifecycles

• Options for controlling data lifecycles

• Make requests

• Consistency in Cloud Storage operations

• Batched requests

• Use long-running operations

• Paginate results

• URI wildcards

• Secure data

• Access control

  • Overview
  • Bucket IP filtering
    * Overview
    * Create a bucket with IP filtering rules
    * Create or update IP filtering rules on an existing bucket
    * Get IP bucket filtering rules
    * List bucket IP filtering rules
    * Delete bucket IP filtering rules
    * Disable bucket IP filtering
    * Bypass bucket IP filtering rules
  • Sharing and collaboration scenarios
  • Access control best practices

• Monitor data and usage

• Use Cloud Audit Logs with Cloud Storage

• Usage logs and storage logs

• Use Cloud Audit Logs with storage batch operations

• Use Cloud Logs with storage batch operations

• Use Cloud Audit Logs with Storage Insights

• Use gRPC client-side metrics

• Use client-side traces

• Protection, backup, and recovery

• Overview

• Soft delete

  • Overview
  • Set and manage soft delete policies
  • Use soft-deleted objects
  • Use soft-deleted buckets
  • Set a default soft delete retention duration
  • Use soft delete recommendations
  • Disable soft delete

• Mount buckets with Cloud Storage FUSE

• Overview

• Quickstart

• Install Cloud Storage FUSE

• Mount buckets

• Performance

  • Performance tuning best practices
  • Profile-based configurations for AI/ML workloads
  • Automated configuration values for high-performance machine types
  • Use pre-configured GKE YAML files to optimize Cloud Storage FUSE performance

• Work across products, Clouds, and platforms

• Best practices for media workloads

• Interoperability

• Use Cloud Storage with Big Data

• Integration with Google Cloud Platform services and tools

• Troubleshoot

• Troubleshooting common issues

• Troubleshooting Storage Insights issues

• Troubleshooting Cloud Storage FUSE issues

Create and manage folders

This page describes how to create, list, upload, delete, and get the metadata offolders in buckets with hierarchical namespace enabled.

Before you begin

Ensure that your bucket has hierarchical namespace enabled. For detailed instructions about enabling hierarchical namespace on a bucket, see Create buckets with hierarchical namespace enabled.

Create a folder

This section describes how to create a folder.

Roles required

In order to get the required permissions for creating folders, ask your administrator to grant you the Storage Object User (roles/storage.objectUser) IAM role on the bucket. This role contains the storage.folders.create permission, which is required to create a folder.

For instructions on granting roles on buckets, see Use IAM with buckets.

You might also be able to get this permission with other custom roles orpredefined roles. For a more permissive role that lets you manage folders in addition to creating folders, ask your administrator to grant you any one of the following roles:

• Storage Folder Admin (roles/storage.folderAdmin)
• Storage Object Admin (roles/storage.objectAdmin)
• Storage Admin (roles/storage.admin)

To see which roles are associated with which permissions, refer to IAM roles for Cloud Storage.

Console

1. In the Google Cloud console, go to the Cloud Storage Buckets page.
   Go to Buckets
2. In the bucket list, click the name of the bucket you want to create the folder in.
3. In the Bucket details page, click Create folder to create an empty folder.
4. In the Name field, enter a name for your folder. For naming considerations, see Considerations.
5. Click Create.
   Your newly created folder appears in the Folder browser pane.

Command line

1. In the Google Cloud console, activate Cloud Shell.
   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.
2. In your development environment, run the gcloud storage folders create command:
   gcloud storage folders create --recursive gs://BUCKET_NAME/FOLDER_NAME
   Where:
   • BUCKET_NAME is the name of your bucket. For example,my-bucket.
   • FOLDER_NAME is the name of the folder you want to create. For example, my-folder/. For information about folder names, see thefolders overview documentation.
   • --recursive is a flag that automatically creates all non-existent parent folders along with the folder. This setting is optional when parent folders already exist.
     If the request is successful, the command returns the following message:
     Completed 1/1

Client Libraries

C++

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

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

C#

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

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

Go

For more information, see theCloud Storage Go API reference documentation.

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

Java

For more information, see theCloud Storage Java API reference documentation.

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

Node.js

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

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

PHP

For more information, see theCloud Storage PHP API reference documentation.

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

Python

For more information, see theCloud Storage Python API reference documentation.

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

Ruby

For more information, see theCloud Storage Ruby API reference documentation.

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

REST APIs

JSON API

1. Have gcloud CLI installed and initialized, which lets you generate an access token for the Authorization header.
2. Create a JSON file that contains the settings for the folder, which must include aname for the folder. See theFolders: Insert documentation for a complete list of settings. The following are required settings to include:
   {
   "name": "FOLDER_NAME",
   }
   Where FOLDER_NAME is the name of the folder you want to create. For example, my-folder/. For information about folder names, see thefolders overview documentation.
3. Use cURL to call theJSON API:
   curl -X POST --data-binary @JSON_FILE_NAME \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/folders?recursive=true"
   Where:
   • JSON_FILE_NAME is the name of the JSON file that contains the settings for the folder.
   • BUCKET_NAME is the name of the bucket where you want to create the folder.
   • recursive is set to true to automatically create all the non-existent parent folders along with the folder. This setting is optional when parent folders already exist.

List folders

This section describes how to list folders.

Roles required

In order to get the required permissions for listing folders, ask your administrator to grant you the Storage Object Viewer (roles/storage.objectViewer) IAM role on the bucket. This role contains the storage.folders.list permission, which is required to list folders.

For instructions on granting roles on buckets, see Use IAM with buckets.

You might also be able to get this permission with other custom roles orpredefined roles. For a more permissive role that lets you manage folders in addition to listing folders, ask your administrator to grant you any one of the following roles:

• Storage Folder Admin (roles/storage.folderAdmin)
• Storage Object Admin (roles/storage.objectAdmin)
• Storage Object User (roles/storage.objectUser)
• Storage Admin (roles/storage.admin)

To see which roles are associated with which permissions, refer to IAM roles for Cloud Storage.

Console

1. In the Google Cloud console, go to the Cloud Storage Buckets page.
   Go to Buckets
2. In the bucket list, click the name of the bucket whose folders you want to list.
3. From the Folder browser pane, use the expander arrow to expand the list of folders within your bucket.
   A list displays the folders, simulated folders, and managed folders in your bucket.

Command line

To list all folders in a bucket, run the gcloud storage folders list command:

gcloud storage folders list gs://BUCKET_NAME/

Where:

• BUCKET_NAME is the name of the bucket that contains the folders you want to list. For example, my-bucket.

A successful response looks like the following example:

bucket: hns-bucket id: hns-bucket/A/ kind: storage#folder name: A/ selfLink: https://www.googleapis.com/storage/v1/b/hns-bucket/f/A timeCreated: '2023-05-05T16:32:08.878000+00:00' updated: '2023-05-05T16:32:08.878000+00:00'

bucket: hns-bucket id: hns-bucket/B/ kind: storage#folder name: B/ selfLink: https://www.googleapis.com/storage/v1/b/hns-bucket/f/B timeCreated: '2023-05-05T16:32:08.878000+00:00' updated: '2023-05-05T16:32:08.878000+00:00'

bucket: hns-bucket id: hns-bucket/B/D/ kind: storage#folder name: D/ selfLink: https://www.googleapis.com/storage/v1/b/hns-bucket/f/B/D timeCreated: '2023-05-05T16:32:08.878000+00:00' updated: '2023-05-05T16:32:08.878000+00:00'

bucket: hns-bucket id: hns-bucket/C/ kind: storage#folder name: C/ selfLink: https://www.googleapis.com/storage/v1/b/hns-bucket/f/C timeCreated: '2023-05-05T16:32:08.878000+00:00' updated: '2023-05-05T16:32:08.878000+00:00'

bucket: hns-bucket id: hns-bucket/C/E/ kind: storage#folder name: E/ selfLink: https://www.googleapis.com/storage/v1/b/hns-bucket/f/C/E timeCreated: '2023-05-05T16:32:08.878000+00:00' updated: '2023-05-05T16:32:08.878000+00:00' ...

Client libraries

C++

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

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

C#

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

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

Go

For more information, see theCloud Storage Go API reference documentation.

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

Java

For more information, see theCloud Storage Java API reference documentation.

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

Node.js

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

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

PHP

For more information, see theCloud Storage PHP API reference documentation.

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

Python

For more information, see theCloud Storage Python API reference documentation.

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

Ruby

For more information, see theCloud Storage Ruby API reference documentation.

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

REST APIs

JSON API

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 arequest to list folders:
   curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/folders"
   Where BUCKET_NAME is the name of the bucket that contains the folders you want to list. For example,my-bucket.

Upload a folder

This section describes how to upload folders to a bucket.

Roles required

In order to get the required permissions for uploading folders, ask your administrator to grant you the Storage Object User (roles/storage.objectUser) IAM role on the bucket. This role contains the storage.folders.create permission, which is required to upload a folder.

For instructions on granting roles on buckets, see Use IAM with buckets.

You might also be able to get this permission with other custom roles orpredefined roles. For a more permissive role that lets you manage folders in addition to uploading folders, ask your administrator to grant you any one of the following roles:

• Storage Folder Admin (roles/storage.folderAdmin)
• Storage Object Admin (roles/storage.objectAdmin)
• Storage Admin (roles/storage.admin)

To see which roles are associated with which permissions, refer to IAM roles for Cloud Storage.

Console

1. In the Google Cloud console, go to the Cloud Storage Buckets page.
   Go to Buckets
2. In the list of buckets, click the name of the bucket you want to upload the folder to.
3. In the Bucket details tab, perform one of the following actions:
   • Drag folders from your desktop or file manager to the main pane in the Google Cloud console.
   • Click Upload > Upload folder, select the folder that you want to upload in the dialog that appears, then click Open.

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

Command line

Use the gcloud storage cp command with the --recursive flag:

gcloud storage cp --recursive FOLDER_LOCATION gs://DESTINATION_BUCKET_NAME

Where:

• FOLDER_LOCATION is the local path to your folder you want to upload. For example, ../uploads/my-folder/.
• DESTINATION_BUCKET_NAME is the name of the bucket to which you are uploading your folder. For example,my-bucket.

If successful, the response looks like the following example:

Copying file://DIR/OBJ1 at 10.06.32 PM.png to gs://BUCKET_NAME/DIR/OBJ1 at 10.06.32 PM.png Copying file://DIR/OBJ1 at 10.06.32 PM.png to gs://BUCKET_NAME/DIR/OBJ1 at 10.06.32 PM.png Completed files 2/2 | 1.7MiB/1.7MiB

Delete a folder

This section describes how to delete folders.

Roles required

In order to get the required permissions for deleting folders, ask your administrator to grant you the Storage Object User (roles/storage.objectUser) IAM role on the bucket. This role contains the following permissions, which are required to delete a folder:

• storage.folders.delete
• storage.managedFolders.delete (Only required if a managed folder exists with the same path as the folder)

For instructions on granting roles on buckets, see Use IAM with buckets.

You might also be able to get these permissions with other custom roles orpredefined roles. For a more permissive role that lets you manage folders in addition to deleting folders, ask your administrator to grant you any one of the following roles:

• Storage Folder Admin (roles/storage.folderAdmin)
• Storage Object Admin (roles/storage.objectAdmin)
• Storage Admin (roles/storage.admin)

To see which roles are associated with which permissions, refer toIAM roles for Cloud Storage.

Console

1. In the Google Cloud console, go to the Cloud Storage Buckets page.
   Go to Buckets
2. In the bucket list, click the name of the bucket whose folders you want to delete.
3. From the Folder browser pane, use the expander arrow to expand the list of folders within your bucket.
4. Find the folder you want to delete.
5. Click the folder's More actions menu.
6. Click Delete folder.
7. To confirm that you want to delete the folder, typeDELETE in Delete field.
8. Click Delete.
   The folder and its contents, including stored objects and other managed folders, are deleted from your Cloud Storage bucket.

Command line

To delete an empty folder, run the gcloud storage folders delete command:

gcloud storage folders delete gs://BUCKET_NAME/FOLDER_NAME

Where:

• BUCKET_NAME is the name of the bucket. For example, my-bucket.
• FOLDER_NAME is the name of the folder you want to delete. For example, my-folder/.

Client libraries

C++

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

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

C#

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

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

Go

For more information, see theCloud Storage Go API reference documentation.

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

Java

For more information, see theCloud Storage Java API reference documentation.

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

Node.js

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

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

PHP

For more information, see theCloud Storage PHP API reference documentation.

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

Python

For more information, see theCloud Storage Python API reference documentation.

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

Ruby

For more information, see theCloud Storage Ruby API reference documentation.

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

REST APIs

JSON API

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 Folderrequest:
   curl -X DELETE -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/folders/FOLDER_NAME"
   Where:
   • BUCKET_NAME is the name of the bucket that contains the folder you want to delete. For example,my-bucket.
   • FOLDER_NAME is the URL-encoded name of the folder you want to delete. For example, my-folder/, URL-encoded as my-folder%2F.

This section describes how to get the metadata of a folder.

Roles required

In order to get the required permissions for getting the metadata of a folder, ask your administrator to grant you the Storage Object Viewer (roles/storage.objectViewer) IAM role on the bucket. This role contains the storage.folders.get permission, which is required to get the metadata of a folder.

For instructions on granting roles on buckets, see Use IAM with buckets.

You might also be able to get this permission with other custom roles orpredefined roles. For a more permissive role that lets you manage folders in addition to getting the metadata of a folder, ask your administrator to grant you any one of the following roles:

• Storage Folder Admin (roles/storage.folderAdmin)
• Storage Object Admin (roles/storage.objectAdmin)
• Storage Object User (roles/storage.objectUser)
• Storage Admin (roles/storage.admin)

To see which roles are associated with which permissions, refer to IAM roles for Cloud Storage.

Command line

To get the metadata of a folder, run the gcloud storage folders describe command:

gcloud storage folders describe gs://BUCKET_NAME/FOLDER_NAME

Where:

• BUCKET_NAME is the name of the bucket that contains the folder whose metadata you want to retrieve. For example, my-bucket.
• FOLDER_NAME is the name of the folder whose metadata you want to retrieve. For example, my-folder/.

Client libraries

REST APIs

JSON API

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 GETFolder request:
   curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/folders/FOLDER_NAME"
   Where:
   • BUCKET_NAME is the name of the bucket that contains the folder whose metadata you want to retrieve. For example, my-bucket.
   • FOLDER_NAME is the URL-encoded name of the folder whose metadata you want to retrieve. For example, my-folder/, URL-encoded as my-folder%2F.

Manage access on a folder

This section describes how to manage access on your folder by setting Identity and Access Management (IAM) policies, so you can get fine-grained access control over specific groups of objects within a bucket.

To manage access on your folder, follow these steps:

1. Enable management on your folder by creating a managed folderwith the same name as your existing folder. For detailed instructions, seeCreate a managed folder.
2. Set and manage Identity and Access Management (IAM) policies on the managed folder you created.

What's next

• Rename folders.
• Create buckets with hierarchical namespace enabled.
• Use hierarchical namespace for Hadoop workloads.
• Optimize folder management.

Try it for yourself

If you're new to Google Cloud, create an account to evaluate how Cloud Storage performs in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

Try Cloud Storage free

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

Last updated 2025-12-15 UTC.