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.
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 following command:
gcloud alpha 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/
.--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 a local development environment.
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 a local development environment.
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 a local development environment.
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 a local development environment.
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 a local development environment.
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 a local development environment.
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 a local development environment.
REST APIs
JSON API
Have gcloud CLI installed and initialized, in order to generate an access token for the
Authorization
header.Alternatively, you can create an access token using the OAuth 2.0 Playground and include it in 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 common settings to include: FOLDER_NAME
is the name of the folder you want to create. For example,my-folder/
.- 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=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.
{ "name": "FOLDER_NAME", }
Where:
List folders
This section describes how to list folders.
Command line
To list all folders in a bucket, run the following command:
gcloud alpha 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 a local development environment.
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 a local development environment.
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 a local development environment.
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 a local development environment.
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 a local development environment.
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 a local development environment.
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 a local development environment.
C++
Go
Java
Node.js
PHP
Python
Ruby
REST APIs
JSON API
Have gcloud CLI installed and initialized, in order to generate an access token for the
Authorization
header.Alternatively, you can create an access token using the OAuth 2.0 Playground and include it in 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. You can only delete a folder when it's empty, meaning it cannot contain any objects or other folders.
Command line
To delete an empty folder, run the following command:
gcloud alpha 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 a local development environment.
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 a local development environment.
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 a local development environment.
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 a local development environment.
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 a local development environment.
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 a local development environment.
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 a local development environment.
C++
Go
Java
Node.js
PHP
Python
Ruby
REST APIs
JSON API
Have gcloud CLI installed and initialized, in order to generate an access token for the
Authorization
header.Alternatively, you can create an access token using the OAuth 2.0 Playground and include it in 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 following command:
gcloud alpha 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 a local development environment.
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 a local development environment.
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 a local development environment.
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 a local development environment.
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 a local development environment.
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 a local development environment.
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 a local development environment.
C++
Go
Java
Node.js
PHP
Python
Ruby
REST APIs
JSON API
Have gcloud CLI installed and initialized, in order to generate an access token for the
Authorization
header.Alternatively, you can create an access token using the OAuth 2.0 Playground and include it in 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
.
What's next
- Rename folders.
- Create and manage buckets with hierarchical namespace enabled.
- Use hierarchical namespace for Hadoop workloads.
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