Create and manage folders

This page describes how to create and manage folders in buckets with hierarchical namespace enabled. Specifically, this page shows you how to create, list, and delete your folders, as well as how to get a folder's metadata.

For more information about these folder operations, see Folder operations.

Before you begin

To follow these instructions, your bucket must have hierarchical namespace enabled. If you need to create a bucket with this feature, see Create buckets with hierarchical namespace enabled.

Create a folder

This section describes how to create a new folder in your bucket.

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 or predefined 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

In the Google Cloud console, go to the Cloud Storage Buckets page.

Go to Buckets
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.

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.

namespace storagecontrol = google::cloud::storagecontrol_v2;
[](storagecontrol::StorageControlClient client,
   std::string const& bucket_name, std::string const& folder_id) {
  auto const parent = std::string{"projects/_/buckets/"} + bucket_name;
  auto folder = client.CreateFolder(
      parent, google::storage::control::v2::Folder{}, folder_id);
  if (!folder) throw std::move(folder).status();

  std::cout << "Created folder: " << folder->name() << "\n";
}

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.

using Google.Cloud.Storage.Control.V2;
using System;

public class StorageControlCreateFolderSample
{
    public Folder StorageControlCreateFolder(string bucketName = "your-unique-bucket-name",
        string folderName = "your_folder_name")
    {
        StorageControlClient storageControl = StorageControlClient.Create();

        var request = new CreateFolderRequest
        {
            // Set project to "_" to signify globally scoped bucket
            Parent = BucketName.FormatProjectBucket("_", bucketName),
            FolderId = folderName
        };

        Folder folder = storageControl.CreateFolder(request);

        Console.WriteLine($"Folder {folderName} created in bucket {bucketName}");
        return folder;
    }
}

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.

import (
	"context"
	"fmt"
	"io"
	"time"

	control "cloud.google.com/go/storage/control/apiv2"
	"cloud.google.com/go/storage/control/apiv2/controlpb"
)

// createFolder creates a folder in the bucket with the given name.
func createFolder(w io.Writer, bucket, folder string) error {
	// bucket := "bucket-name"
	// folder := "folder-name"

	ctx := context.Background()
	client, err := control.NewStorageControlClient(ctx)
	if err != nil {
		return fmt.Errorf("NewStorageControlClient: %w", err)
	}
	defer client.Close()

	ctx, cancel := context.WithTimeout(ctx, time.Second*30)
	defer cancel()

	req := &controlpb.CreateFolderRequest{
		Parent:   fmt.Sprintf("projects/_/buckets/%v", bucket),
		FolderId: folder,
	}
	f, err := client.CreateFolder(ctx, req)
	if err != nil {
		return fmt.Errorf("CreateFolder(%q): %w", folder, err)
	}

	fmt.Fprintf(w, "created folder with path %q", f.Name)
	return nil
}

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.

import com.google.storage.control.v2.BucketName;
import com.google.storage.control.v2.CreateFolderRequest;
import com.google.storage.control.v2.Folder;
import com.google.storage.control.v2.StorageControlClient;
import java.io.IOException;

public final class CreateFolder {

  public static void createFolder(String bucketName, String folderName) throws IOException {
    // The name of the bucket
    // String bucketName = "your-unique-bucket-name";

    // The name of the folder within the bucket
    // String folderName = "your-unique-folder-name";

    try (StorageControlClient storageControl = StorageControlClient.create()) {

      CreateFolderRequest request =
          CreateFolderRequest.newBuilder()
              // Set project to "_" to signify globally scoped bucket
              .setParent(BucketName.format("_", bucketName))
              .setFolderId(folderName)
              .build();

      Folder newFolder = storageControl.createFolder(request);

      System.out.printf("Created folder: %s%n", newFolder.getName());
    }
  }
}

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.

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */

// The name of your GCS bucket
// const bucketName = 'bucketName';

// The name of the folder to be created
// const folderName = 'folderName';

// Imports the Control library
const {StorageControlClient} = require('@google-cloud/storage-control').v2;

// Instantiates a client
const controlClient = new StorageControlClient();

async function callCreateFolder() {
  const bucketPath = controlClient.bucketPath('_', bucketName);

  // Create the request
  const request = {
    parent: bucketPath,
    folderId: folderName,
  };

  // Run request
  const [response] = await controlClient.createFolder(request);
  console.log(`Created folder: ${response.name}.`);
}

callCreateFolder();

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.

use Google\Cloud\Storage\Control\V2\Client\StorageControlClient;
use Google\Cloud\Storage\Control\V2\CreateFolderRequest;

/**
 * Create a new folder in an existing bucket.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 * @param string $folderName The name of your folder inside the bucket.
 *        (e.g. 'my-folder')
 */
function create_folder(string $bucketName, string $folderName): void
{
    $storageControlClient = new StorageControlClient();

    // Set project to "_" to signify global bucket
    $formattedName = $storageControlClient->bucketName('_', $bucketName);

    $request = new CreateFolderRequest([
        'parent' => $formattedName,
        'folder_id' => $folderName,
    ]);

    $folder = $storageControlClient->createFolder($request);

    printf('Created folder: %s', $folder->getName());
}

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.

from google.cloud import storage_control_v2


def create_folder(bucket_name: str, folder_name: str) -> None:
    # The ID of your GCS bucket
    # bucket_name = "your-unique-bucket-name"

    # The name of the folder to be created
    # folder_name = "folder-name"

    storage_control_client = storage_control_v2.StorageControlClient()
    # The storage bucket path uses the global access pattern, in which the "_"
    # denotes this bucket exists in the global namespace.
    project_path = storage_control_client.common_project_path("_")
    bucket_path = f"{project_path}/buckets/{bucket_name}"

    request = storage_control_v2.CreateFolderRequest(
        parent=bucket_path,
        folder_id=folder_name,
    )
    response = storage_control_client.create_folder(request=request)

    print(f"Created folder: {response.name}")

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.

def create_folder bucket_name:, folder_name:
  # The ID of your GCS bucket
  # bucket_name = "your-unique-bucket-name"

  # The name of the folder to be created
  # folder_name = "folder-name"

  require "google/cloud/storage/control"

  storage_control = Google::Cloud::Storage::Control.storage_control

  # The storage bucket path uses the global access pattern, in which the "_"
  # denotes this bucket exists in the global namespace.
  bucket_path = storage_control.bucket_path project: "_", bucket: bucket_name

  request = Google::Cloud::Storage::Control::V2::CreateFolderRequest.new parent: bucket_path, folder_id: folder_name

  response = storage_control.create_folder request

  puts "Created folder: #{response.name}"
end

Rust

use google_cloud_storage::{client::StorageControl, model::Folder};

pub async fn sample(client: &StorageControl, bucket_id: &str) -> anyhow::Result<()> {
    const ID: &str = "example-folder-id";
    let folder = client
        .create_folder()
        .set_parent(format!("projects/_/buckets/{bucket_id}"))
        .set_folder_id(ID)
        .set_folder(Folder::new())
        .send()
        .await?;
    println!("folder successfully created {folder:?}");
    Ok(())
}

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.

Upload a folder

This section describes how to upload folders to a bucket. Uploading a folder uses an underlying create folder operation with batch object upload operations.

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 or predefined 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

In the Google Cloud console, go to the Cloud Storage Buckets page.

Go to Buckets
In the list of buckets, click the name of the bucket you want to upload the folder to.
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, see Troubleshooting.

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

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 or predefined 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)