This page describes how to create, list, delete, and get metadata of folders in buckets with hierarchical namespace enabled.
Create a folder
This section describes how to create a folder.
Console
-
In the Google Cloud console, go to the Cloud Storage Buckets page.
- In the bucket list, click the name of the bucket you want to create the folder in.
- In the Bucket details page, click Create folder to create an empty folder.
- In the Name field, enter a name for your folder. For naming considerations, see Considerations.
-
Click Create.
Your newly created folder appears in the Folder browser pane.
Command line
-
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a Cloud 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 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 the folders 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 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.
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.
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.
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.
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.
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.
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.
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.
REST APIs
JSON API
Have gcloud CLI installed and initialized, which lets you generate an access token for the
Authorization
header.- Create a JSON file that contains the settings for the folder, which must include a
name
for the folder. See the Folders: 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 the folders overview documentation. - Use
cURL
to call the JSON 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.
Console
- In the Google Cloud console, go to the Cloud Storage Buckets page.
In the bucket list, click the name of the bucket whose folders you want to list.
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
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.
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.
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.
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.
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.
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.
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.
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.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
REST APIs
JSON API
Have gcloud CLI installed and initialized, which lets you generate an access token for the
Authorization
header.Use
cURL
to call the JSON API with a request 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
.
Delete a folder
This section describes how to delete folders.
Console
- In the Google Cloud console, go to the Cloud Storage Buckets page.
In the bucket list, click the name of the bucket whose folders you want to delete.
From the Folder browser pane, use the expander arrow
to expand the list of folders within your bucket.Find the folder you want to delete.
Click the folder's
More actions menu.Click Delete folder.
To confirm that you want to delete the folder, type
DELETE
in Delete field.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
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.
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.
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.
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.
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.
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.
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.
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.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
REST APIs
JSON API
Have gcloud CLI installed and initialized, which lets you generate an access token for the
Authorization
header.Use
cURL
to call the JSON API with aDELETE
Folder request: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 asmy-folder%2F
.
Get the metadata of a folder
This section describes how to get the metadata of a folder.
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
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.
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.
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.
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.
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.
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.
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.
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.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
REST APIs
JSON API
Have gcloud CLI installed and initialized, which lets you generate an access token for the
Authorization
header.Use
cURL
to call the JSON API with aGET
Folder 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 asmy-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:
Enable management on your folder by creating a managed folder with the same name as your existing folder. For detailed instructions, see Create a managed folder.
Set and manage Identity and Access Management (IAM) policies on the managed folder you created.
What's next
- Rename folders.
- Create and manage 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