[Hierarchical namespace](https://docs.cloud.google.com/storage/docs/hns-overview.md.txt) lets you organize objects into folders within a
logical file system structure, which helps accelerate data-intensive AI/ML and
analytics workloads. You can only enable hierarchical namespace when you
create a bucket; you can't enable it on an existing bucket.

## Required roles


To get the permission that
you need to create a bucket with hierarchical namespace enabled,

ask your administrator to grant you the
[Storage Admin](https://docs.cloud.google.com/iam/docs/roles-permissions/storage.md.txt#storage.admin) (`roles/storage.admin`) IAM role on the project.


For more information about granting roles, see [Manage access to projects, folders, and organizations](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt).


This predefined role contains the
`storage.buckets.create`
permission,
which is required to
create a bucket with hierarchical namespace enabled.


You might also be able to get
this permission
with [custom roles](https://docs.cloud.google.com/iam/docs/creating-custom-roles.md.txt) or
other [predefined roles](https://docs.cloud.google.com/iam/docs/roles-overview.md.txt#predefined).

## Create a bucket with hierarchical namespace enabled

### Console

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

   [Go to Buckets](https://console.cloud.google.com/storage/browser)
2. Click **Create**.
3. On the **Create a bucket** page, enter your bucket information. After
   each of the following steps, click **Continue** to proceed to the next
   step:

   1. In the **Get started** section, do the following:

      - Enter a globally unique name that meets the
        [bucket name requirements](https://docs.cloud.google.com/storage/docs/buckets.md.txt#naming).

   2. In the **Choose where to store your data** section, do the
      following:

      1. Select a [Location type](https://docs.cloud.google.com/storage/docs/locations.md.txt).

      2. Use the location type's drop-down menu to select a
         [**Location**](https://docs.cloud.google.com/storage/docs/locations.md.txt#available-locations) where object data
         within your bucket will be permanently stored.

         - If you select the [dual-region](https://docs.cloud.google.com/storage/docs/locations.md.txt#location-dr) location
           type, you can also choose to enable
           [turbo replication](https://docs.cloud.google.com/storage/docs/availability-durability.md.txt#turbo-replication) by
           using the relevant checkbox.

   3. In the **Choose how to store your data** section, do the
      following:

      1. Select a [default storage class](https://docs.cloud.google.com/storage/docs/storage-classes.md.txt) for the
         bucket or [Autoclass](https://docs.cloud.google.com/storage/docs/autoclass.md.txt) for automatic storage
         class management of your bucket's data.

      2. In the **Optimize storage for data-intensive workloads** section,
         do the following:

         - To enable [hierarchical namespace](https://docs.cloud.google.com/storage/docs/hns-overview.md.txt), select
           **Enable Hierarchical namespace on this bucket**.

           > [!NOTE]
           > **Note:** Hierarchical namespace can only be enabled when you create the bucket.
           > You can't change this setting after you create the bucket.

   4. In the **Choose how to control access to objects** section, do the following:

      1. Select whether your bucket enforces
         [public access prevention](https://docs.cloud.google.com/storage/docs/public-access-prevention.md.txt).

         > [!NOTE]
         > **Note:** If public access prevention is already enforced by your project's [organization policy](https://docs.cloud.google.com/storage/docs/org-policy-constraints.md.txt#public-access-prevention), the **Prevent public access** checkbox is locked.

      2. Select **Uniform** to enable uniform bucket-level access on the bucket.

      3. Optionally, configure
         [IP filtering for the bucket](https://docs.cloud.google.com/storage/docs/ip-filtering-overview.md.txt).

   5. In the **Choose how to protect object data** section, do the
      following:

      - Select any of the options under **Data protection** that you
        want to set for your bucket.

      - To change the amount of time that [soft delete](https://docs.cloud.google.com/storage/docs/soft-delete.md.txt)
        retains objects after deletion, select the **Soft delete policy** checkbox, and then
        select the **Set custom retention duration** option. Then, specify how long you want to
        retain deleted objects.

        To disable soft delete, for example if the bucket will primarily contain
        short-lived, temporary data, clear the **Soft delete policy** checkbox.
      - To choose how to [encrypt](https://docs.cloud.google.com/storage/docs/encryption.md.txt) your object data,
        click the expander arrow labeled
        **Data encryption**, and do the following:

        - In the **Default encryption key type** section, select the default encryption key for the bucket. If you select **Cloud KMS key** , then provide a [Cloud Key Management Service key](https://docs.cloud.google.com/storage/docs/encryption/using-customer-managed-keys.md.txt).
        - In the **Encryption enforcement rules** section, for **Key types** , select [which encryption types to
          allow or restrict](https://docs.cloud.google.com/storage/docs/encryption/enforce-encryption-types) for new objects in the bucket.
4. Click **Create**.

To learn how to get detailed error information about failed Cloud Storage
operations in the Google Cloud console, see
[Troubleshooting](https://docs.cloud.google.com/storage/docs/troubleshooting.md.txt#trouble-console).

### Command line

1. In the Google Cloud console, activate Cloud Shell.

   [Activate Cloud Shell](https://console.cloud.google.com/?cloudshell=true)


   At the bottom of the Google Cloud console, a
   [Cloud Shell](https://docs.cloud.google.com/shell/docs/how-cloud-shell-works.md.txt)
   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 buckets create`](https://docs.cloud.google.com/sdk/gcloud/reference/storage/buckets/create.md.txt)
   command:

   ```
   gcloud storage buckets create gs://BUCKET_NAME --location=BUCKET_LOCATION --uniform-bucket-level-access --enable-hierarchical-namespace
   ```

   Where:
   - `BUCKET_NAME` is the name you want to give your bucket, subject to [naming requirements](https://docs.cloud.google.com/storage/docs/buckets.md.txt#naming). For example, `my-bucket`.
   - `BUCKET_LOCATION` is the [location](https://docs.cloud.google.com/storage/docs/locations.md.txt) of your bucket. For example, `us-east1`.
   - `--uniform-bucket-level-access`: Enable [uniform bucket-level access](https://docs.cloud.google.com/storage/docs/uniform-bucket-level-access.md.txt) for the bucket.  

     > [!NOTE]
     > **Note:** Enabling uniform bucket-level access on a bucket is required for creating a bucket with hierarchical namespace enabled.

   - `--enable-hierarchical-namespace`: Enable [hierarchical namespace](https://docs.cloud.google.com/storage/docs/hns-overview.md.txt) for the bucket. You cannot enable hierarchical namespace in an existing bucket.

   If the request is successful, the command returns the following message:

   ```
   Creating gs://BUCKET_NAME/...
   ```

   Set the following flags to have greater control over the creation of your bucket:
   - `--project`: Specify the project ID or project number that your bucket will be associated with. For example, `my-project`.
   - `--default-storage-class`: Specify the default [storage
     class](https://docs.cloud.google.com/storage/docs/storage-classes) of your bucket. For example, `STANDARD`. To automatically manage the storage classes of your objects, use the `--enable-autoclass` flag instead. For more information, see [Autoclass](https://docs.cloud.google.com/storage/docs/autoclass.md.txt).

   For a complete list of options for creating buckets using the Google Cloud CLI, see
   [`buckets create` options](https://docs.cloud.google.com/sdk/gcloud/reference/storage/buckets/create.md.txt#FLAGS).

   For example:

   ```
   gcloud storage buckets create gs://BUCKET_NAME --project=PROJECT_ID --default-storage-class=STORAGE_CLASS --location=BUCKET_LOCATION --uniform-bucket-level-access --enable-hierarchical-namespace
   ```

### Client Libraries

### C++


For more information, see the
[Cloud Storage C++ API
reference documentation](https://docs.cloud.google.com/cpp/docs/reference/storage/latest).


To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see

[Set up authentication for client libraries](https://docs.cloud.google.com/storage/docs/authentication.md.txt#client-libs).

```c++
namespace gcs = ::google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name) {
  auto metadata = client.CreateBucket(
      bucket_name,
      gcs::BucketMetadata()
          .set_hierarchical_namespace(gcs::BucketHierarchicalNamespace{true})
          .set_iam_configuration(gcs::BucketIamConfiguration{
              gcs::UniformBucketLevelAccess{true, {}}, std::nullopt}));
  if (!metadata) throw std::move(metadata).status();

  std::cout << "Bucket " << metadata->name() << " created."
            << "\nFull Metadata: " << *metadata << "\n";
}
```

### C#


For more information, see the
[Cloud Storage C# API
reference documentation](https://cloud.google.com/dotnet/docs/reference/Google.Cloud.Storage.V1/latest).


To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see

[Set up authentication for client libraries](https://docs.cloud.google.com/storage/docs/authentication.md.txt#client-libs).

```c#
using Google.Apis.Storage.v1.Data;
using Google.Cloud.Storage.V1;
using System;

public class CreateBucketWithHierarchicalNamespaceEnabledSample
{
    public Bucket CreateBucketWithHierarchicalNamespace(
        string projectId = "your-project-id",
        string bucketName = "your-unique-bucket-name")
    {
        var storage = StorageClient.Create();
        var bucket = storage.CreateBucket(projectId,
            new Bucket
            {
                Name = bucketName,
                IamConfiguration = new Bucket.IamConfigurationData
                {
                    UniformBucketLevelAccess = new Bucket.IamConfigurationData.UniformBucketLevelAccessData { Enabled = true }
                },
                HierarchicalNamespace = new Bucket.HierarchicalNamespaceData { Enabled = true }
            });
        Console.WriteLine($"Created {bucketName} with Hierarchical Namespace enabled.");
        return bucket;
    }
}
```

### Go


For more information, see the
[Cloud Storage Go API
reference documentation](https://pkg.go.dev/cloud.google.com/go/storage).


To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see

[Set up authentication for client libraries](https://docs.cloud.google.com/storage/docs/authentication.md.txt#client-libs).

```go
import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/storage"
)

// createBucketHierarchicalNamespace creates a new bucket with hierarchical
// namespace features enabled.
func createBucketHierarchicalNamespace(w io.Writer, projectID, bucketName string) error {
	// projectID := "my-project-id"
	// bucketName := "bucket-name"

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

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

	attrs := &storage.BucketAttrs{
		HierarchicalNamespace: &storage.HierarchicalNamespace{
			Enabled: true,
		},
		// Hierarchical namespace buckets must use uniform bucket-level access.
		UniformBucketLevelAccess: storage.UniformBucketLevelAccess{
			Enabled: true,
		},
	}
	bucket := client.Bucket(bucketName)
	if err := bucket.Create(ctx, projectID, attrs); err != nil {
		return fmt.Errorf("Bucket(%q).Create: %w", bucketName, err)
	}
	fmt.Fprintf(w, "Created bucket %v with hierarchical namespace enabled\n", bucketName)
	return nil
}
```

### Java


For more information, see the
[Cloud Storage Java API
reference documentation](https://cloud.google.com/java/docs/reference/google-cloud-storage/latest/overview).


To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see

[Set up authentication for client libraries](https://docs.cloud.google.com/storage/docs/authentication.md.txt#client-libs).

```java
import com.google.cloud.storage.Bucket;
import com.google.cloud.storage.BucketInfo;
import com.google.cloud.storage.BucketInfo.HierarchicalNamespace;
import com.google.cloud.storage.BucketInfo.IamConfiguration;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

public final class CreateHierarchicalNamespaceBucket {

  public static void createHierarchicalNamespaceBucket(String projectId, String bucketName)
      throws Exception {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID to give your GCS bucket
    // String bucketName = "your-unique-bucket-name";
    StorageOptions storageOptions = StorageOptions.newBuilder().setProjectId(projectId).build();
    try (Storage storage = storageOptions.getService()) {

      BucketInfo bucketInfo =
          BucketInfo.newBuilder(bucketName)
              .setIamConfiguration(
                  // Hierarchical namespace buckets must use uniform bucket-level access.
                  IamConfiguration.newBuilder().setIsUniformBucketLevelAccessEnabled(true).build())
              .setHierarchicalNamespace(HierarchicalNamespace.newBuilder().setEnabled(true).build())
              .build();

      Bucket bucket = storage.create(bucketInfo);

      System.out.printf(
          "Created bucket %s with Hierarchical Namespace enabled.%n", bucket.getName());
    }
  }
}
```

### Node.js


For more information, see the
[Cloud Storage Node.js API
reference documentation](https://cloud.google.com/nodejs/docs/reference/storage/latest).


To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see

[Set up authentication for client libraries](https://docs.cloud.google.com/storage/docs/authentication.md.txt#client-libs).

```javascript
/**
 * 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 library
const {Storage} = require('@google-cloud/storage');

// Creates a client
// The bucket in the sample below will be created in the project associated with this client.
// For more information, please see https://cloud.google.com/docs/authentication/production or https://googleapis.dev/nodejs/storage/latest/Storage.html
const storage = new Storage();

async function createBucketWithHierarchicalNamespace() {
  const [bucket] = await storage.createBucket(bucketName, {
    iamConfiguration: {
      uniformBucketLevelAccess: {
        enabled: true,
      },
    },
    hierarchicalNamespace: {
      enabled: true,
    },
  });

  console.log(
    `Created '${bucket.name}' with hierarchical namespace enabled.`
  );
}

createBucketWithHierarchicalNamespace().catch(console.error);
```

### PHP


For more information, see the
[Cloud Storage PHP API
reference documentation](https://googleapis.github.io/google-cloud-php/#/docs/google-cloud/latest/storage/storageclient).


To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see

[Set up authentication for client libraries](https://docs.cloud.google.com/storage/docs/authentication.md.txt#client-libs).

```php
use Google\Cloud\Storage\StorageClient;

/**
 * Create a new bucket with Hierarchical Namespace enabled.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 */
function create_bucket_hierarchical_namespace(string $bucketName): void
{
    $storage = new StorageClient();
    $bucket = $storage->createBucket($bucketName, [
        'hierarchicalNamespace' => ['enabled' => true],
        'iamConfiguration' => ['uniformBucketLevelAccess' => ['enabled' => true]]
    ]);

    printf('Created bucket %s with Hierarchical Namespace enabled.', $bucket->name());
}
```

### Python


For more information, see the
[Cloud Storage Python API
reference documentation](https://cloud.google.com/python/docs/reference/storage/latest).


To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see

[Set up authentication for client libraries](https://docs.cloud.google.com/storage/docs/authentication.md.txt#client-libs).

```python
from google.cloud import storage


def create_bucket_hierarchical_namespace(bucket_name):
    """Creates a bucket with hierarchical namespace enabled."""
    # The ID of your GCS bucket
    # bucket_name = "your-bucket-name"

    storage_client = storage.Client()
    bucket = storage_client.bucket(bucket_name)
    bucket.iam_configuration.uniform_bucket_level_access_enabled = True
    bucket.hierarchical_namespace_enabled = True
    bucket.create()

    print(f"Created bucket {bucket_name} with hierarchical namespace enabled.")

```

### Ruby


For more information, see the
[Cloud Storage Ruby API
reference documentation](https://googleapis.dev/ruby/google-cloud-storage/latest/Google/Cloud/Storage.html).


To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see

[Set up authentication for client libraries](https://docs.cloud.google.com/storage/docs/authentication.md.txt#client-libs).

```ruby
def create_bucket_hierarchical_namespace bucket_name:
  # The ID to give your GCS bucket
  # bucket_name = "your-unique-bucket-name"

  require "google/cloud/storage"

  storage = Google::Cloud::Storage.new

  hierarchical_namespace = Google::Apis::StorageV1::Bucket::HierarchicalNamespace.new enabled: true

  storage.create_bucket bucket_name do |b|
    b.uniform_bucket_level_access = true
    b.hierarchical_namespace = hierarchical_namespace
  end

  puts "Created bucket #{bucket_name} with Hierarchical Namespace enabled."
end
```

### Rust

```rust
use google_cloud_storage::{
    client::StorageControl,
    model::Bucket,
    model::bucket::iam_config::UniformBucketLevelAccess,
    model::bucket::{HierarchicalNamespace, IamConfig},
};

pub async fn sample(
    client: &StorageControl,
    project_id: &str,
    bucket_id: &str,
) -> anyhow::Result<()> {
    let bucket = client
        .create_bucket()
        .set_parent("projects/_")
        .set_bucket_id(bucket_id)
        .set_bucket(
            Bucket::new()
                .set_project(format!("projects/{project_id}"))
                .set_hierarchical_namespace(HierarchicalNamespace::new().set_enabled(true))
                .set_iam_config(IamConfig::new().set_uniform_bucket_level_access(
                    UniformBucketLevelAccess::new().set_enabled(true),
                )),
        )
        .send()
        .await?;
    println!("successfully created bucket {bucket:?}");
    Ok(())
}
```

### REST APIs

### JSON API

1. Have gcloud CLI [installed and initialized](https://docs.cloud.google.com/sdk/docs/install), which lets
   you generate an access token for the `Authorization` header.

2. Create a JSON file that contains the settings for the bucket, which must include a `name` for the bucket. See the [Buckets: Insert](https://docs.cloud.google.com/storage/docs/json_api/v1/buckets/insert.md.txt) documentation for a complete list of settings. The following are common settings to include:

```json
{
  "name": "BUCKET_NAME",
  "location": "BUCKET_LOCATION",
  "storageClass": "STORAGE_CLASS",
  "hierarchicalNamespace": {
    "enabled": "BOOLEAN"
  },
  "iamConfiguration": {
    "uniformBucketLevelAccess": {
      "enabled": true
  },
},
}
```
3. Where:
   - `BUCKET_NAME` is the name you want to give your bucket, subject to [naming requirements](https://docs.cloud.google.com/storage/docs/buckets.md.txt#naming). For example, `my-bucket`.
   - `BUCKET_LOCATION` is the [location](https://docs.cloud.google.com/storage/docs/locations.md.txt) where you want to store your bucket's [object data](https://docs.cloud.google.com/storage/docs/objects.md.txt). For example, `US-EAST1`.
   - `STORAGE_CLASS` is the default [storage
     class](https://docs.cloud.google.com/storage/docs/storage-classes) of your bucket. For example, `STANDARD`.
   - `hierarchicalNamespace.enabled` is set to `TRUE` to enable [hierarchical namespace](https://docs.cloud.google.com/storage/docs/hns-overview.md.txt) for your bucket. You cannot enable hierarchical namespace in an existing bucket.
4. `uniformBucketLevelAccess.enabled` is set to `TRUE` to enable [uniform bucket-level access for your bucket.
   > [!NOTE]
   > **Note:** Enabling uniform bucket-level access on a bucket is required for creating a bucket with hierarchical namespace enabled.](https://docs.cloud.google.com/storage/docs/uniform-bucket-level-access)
5. [Use](https://docs.cloud.google.com/storage/docs/uniform-bucket-level-access.md.txt)[`cURL`](http://curl.haxx.se/) to call the [JSON API](https://docs.cloud.google.com/storage/docs/json_api.md.txt):

   ```
   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?project=PROJECT_IDENTIFIER"
   ```

   Where:
   - `JSON_FILE_NAME` is name of the JSON file that contains the bucket settings.
   - `PROJECT_IDENTIFIER` is the ID or number of the project that your bucket will be associated with. For example, `my-project`.

## What's next

- [Understand folders](https://docs.cloud.google.com/storage/docs/folders-overview.md.txt).
- [Create and manage folders](https://docs.cloud.google.com/storage/docs/create-folders.md.txt).
- [Get a bucket's metadata](https://docs.cloud.google.com/storage/docs/getting-bucket-metadata.md.txt).
- [Get a bucket's storage layout](https://docs.cloud.google.com/storage/docs/getting-storage-layout.md.txt).
- [List](https://docs.cloud.google.com/storage/docs/listing-buckets.md.txt) and [delete](https://docs.cloud.google.com/storage/docs/deleting-buckets.md.txt) buckets.