All Products
Search

This Product

    Object Storage Service:PutBucket

    Document Center

    Object Storage Service:PutBucket

    Last Updated:Jun 23, 2026

    Call the PutBucket operation to create a bucket.

    Notes

    • An Alibaba Cloud account can create a maximum of 100 buckets in each region.

    • Each region has a corresponding endpoint. For more information about the endpoints for each region, see Endpoints.

    • If you call the PutBucket operation multiple times for the same bucket, the first call creates the bucket and subsequent calls modify its metadata, such as the bucket ACL. This can cause the bucket metadata to be overwritten. Proceed with caution.

    • From 10:00 (UTC+8) on October 13, 2025, OSS will implement a phased adjustment across all regions to enable Block Public Access by default for new buckets created using the API, OSS SDKs, or ossutil. For details about the exact times when the adjustment will take effect in each region, see [Official Announcement] Adjustment to the Public Access Blocking Configurations for Newly Created Buckets. Once Block Public Access is enabled, you cannot configure public access permissions, including public ACLs (public read and public read/write) and bucket policies that allows public access. You can disable this feature after the bucket is created if your business requires public access.

    Permissions

    By default, an Alibaba Cloud account has full permissions. RAM users or RAM roles under an Alibaba Cloud account do not have any permissions by default. The Alibaba Cloud account or account administrator must grant operation permissions through RAM policies or Bucket Policy.

    API

    Action

    Description

    PutBucket

    oss:PutBucket

    Creates a bucket.

    oss:PutBucketAcl

    After creating a bucket, this permission is required to modify the bucket ACL.

    Request syntax

    PUT / HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
x-oss-acl: Permission
Authorization: SignatureValue
<?xml version="1.0" encoding="UTF-8"?>
<CreateBucketConfiguration>
    <StorageClass>Standard</StorageClass>
</CreateBucketConfiguration>

    Request headers

    Name

    Type

    Required

    Example

    Description

    x-oss-acl

    String

    No

    private

    The access control list (ACL) of the bucket. Valid values:

    • public-read-write: Grants public read and write permissions.

    • public-read: Public Read

    • private (default)

    For more information about bucket ACLs, see Set bucket ACLs.

    x-oss-resource-group-id

    String

    No

    rg-aek27tc****

    The ID of the resource group.

    • If you include this header in the request and specify a resource group ID, the created bucket belongs to the specified resource group.

      If you set the resource group ID to rg-default-id, the created bucket belongs to the default resource group.

    • If you do not include this header in the request, the created bucket belongs to the default resource group.

    You can obtain the resource group ID on the Resource Management console or by calling the ListResourceGroups operation. For more information, see View resource groups and ListResourceGroups.

    x-oss-bucket-tagging

    String

    No

    k1=v1&k2=v2

    Specifies the bucket tags.

    x-oss-hns-status

    String

    No

    disabled

    Specifies whether to enable the hierarchical namespace feature for the bucket.

    You can enable the hierarchical namespace feature only when you create a bucket. You cannot change the hierarchical namespace state of an existing bucket.

    • enabled: Enabled

      After you enable the hierarchical namespace feature for a bucket, you can perform directory operations in the bucket, such as creating, deleting, and renaming directories.

    • disabled (default): The feature is disabled.

    x-oss-server-side-encryption

    String

    No

    AES256

    Sets the default server-side encryption method.

    Valid values: KMS, AES256

    Note

    In OSS ON CloudBox scenarios, only AES256 is supported.

    Using the KMS feature incurs a small fee for KMS API calls. For more information about the pricing, see KMS pricing.

    During cross-region replication, if the destination bucket has default server-side encryption enabled and the replication rule is configured with a ReplicaCMKID, the following situations apply:

    • If an object in the source bucket is not encrypted, the object is encrypted using the default encryption method of the destination bucket after it is replicated.

    • If an object in the source bucket is encrypted using SSE-KMS or SSE-OSS, the object retains its original encryption method in the destination bucket.

    For more information, see Cross-region replication with server-side encryption.

    x-oss-server-side-encryption-key-id

    String

    No

    9468da86-3509-4f8d-a61e-6eab1eac****

    The ID of the KMS key. This header is required only when x-oss-server-side-encryption is set to KMS. In other cases, this header must be empty.

    If you use OSS on CloudBox, this parameter is not supported.

    This operation also includes common request headers. For more information, see Common request headers.

    Request elements

    Name

    Type

    Required

    Example

    Description

    StorageClass

    String

    No

    Standard

    The storage class of the bucket. Valid values:

    • Standard (default)

    • IA: Infrequent Access

    • Archive: Archive Storage

    • ColdArchive: Cold Archive

    • DeepColdArchive: Deep Cold Archive

    Parent node: CreateBucketConfiguration

    Child nodes: None

    DataRedundancyType

    String

    No

    LRS

    The data redundancy type of the bucket. Valid values:

    • LRS (default)

      Locally redundant storage (LRS) stores copies of your data on different storage devices in the same zone. This ensures data durability and availability even if two storage devices are damaged at the same time.

    • ZRS

      Zone-redundant storage (ZRS) uses a data redundancy mechanism within multiple zones. ZRS stores the data of an object across multiple zones in the same region. If a zone becomes unavailable, you can still access the data.

    Parent node: CreateBucketConfiguration

    Child nodes: None

    Response headers

    Name

    Type

    Example

    Description

    Location

    String

    /oss-example

    The address of the bucket. The value is a forward slash (/) followed by the bucket name.

    Default value: None

    The response also includes common response headers. For more information, see Common response headers.

    Examples

    • Create a bucket in the default resource group

      PUT / HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Date: Thu, 17 Apr 2025 03:15:40 GMT
x-oss-acl: private
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
<?xml version="1.0" encoding="UTF-8"?>
<CreateBucketConfiguration>
    <StorageClass>Standard</StorageClass>
    <DataRedundancyType>LRS</DataRedundancyType>    
</CreateBucketConfiguration>

    • Sample response

      HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906****
Date: Fri, 24 Feb 2017 03:15:40 GMT
Content-Length: 0
Connection: keep-alive
Server: AliyunOSS
Location: /oss-example

    • Create a bucket in a specific resource group

      Sample request

      PUT / HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Date: Thu, 17 Apr 2025 03:15:40 GMT
x-oss-acl: private
x-oss-resource-group-id: rg-aek27tc********
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
<?xml version="1.0" encoding="UTF-8"?>
<CreateBucketConfiguration>
    <StorageClass>Standard</StorageClass>
</CreateBucketConfiguration>

      Sample response

      HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906****
Date: Fri, 24 Feb 2017 03:15:40 GMT
Content-Length: 0
Connection: keep-alive
Server: AliyunOSS
Location: /oss-example

    SDK

    You can call the PutBucket operation using the OSS SDKs for the following programming languages:

    ossutil command-line tool

    For information about the ossutil command that corresponds to the PutBucket operation, see put-bucket.

    Error codes

    Error code

    HTTP status code

    Description

    InvalidBucketName

    400

    The bucket name does not comply with the naming conventions.

    AccessDenied

    403

    The following are possible causes of the error:

    • User authentication information is not included in the PutBucket request.

    • You do not have the required permissions.

    TooManyBuckets

    400

    The number of created buckets exceeds the upper limit. An Alibaba Cloud account can create a maximum of 100 buckets in the same region.

    BucketAlreadyExists

    409

    • If a bucket has been deleted, the time requirement for creating a bucket with the same name is not met.

      You attempt to create a bucket with a name that was used by a bucket that was recently deleted. After a bucket is deleted, you must wait for several hours (typically 4 to 8 hours) before you can create a bucket with the same name.

    • You call the PutBucket operation using methods such as a RAM user or STS to create a bucket with the same name as an existing bucket.

      Only the original Alibaba Cloud account can re-create a bucket with the same name.

    • You do not have the permissions to call the PutBucketAcl operation. Make sure that the caller is granted the oss:PutBucketAcl permission using a bucket policy or a RAM policy.

    • You attempt to change the hierarchical namespace state of an existing bucket. You can enable the hierarchical namespace feature only when you create a bucket.