All Products
Search

This Product

    Object Storage Service:put-object

    Document Center

    Object Storage Service:put-object

    Last Updated:Jan 12, 2026

    Uploads an object to a bucket.

    Usage notes

    • The object to upload cannot be larger than 5 GB.

    • By default, if an object that has the same name already exists and you have access permissions for the object, the new object overwrites the existing one.

    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

    PutObject

    oss:PutObject

    Uploads an object.

    oss:PutObjectTagging

    Required if you specify object tags by using the x-oss-tagging header when you upload an object.

    kms:GenerateDataKey

    Required if the X-Oss-Server-Side-Encryption: KMS header is set to KMS when you upload an object.

    kms:Decrypt

    Command syntax

    ossutil api put-object --bucket value --key value [flags]

    Parameter

    Type

    Description

    --body

    string

    The request body.

    --bucket

    string

    The name of the bucket.

    --cache-control

    string

    The caching behavior of the object.

    --content-disposition

    string

    The filename of the object when it is downloaded.

    --content-encoding

    string

    The encoding format of the object content.

    --expires

    string

    The expiration time.

    --forbid-overwrite

    boolean

    Whether to overwrite an existing object that has the same name.

    --key

    string

    The full path of the object.

    --metadata

    stringArray

    The metadata of the object. To specify custom metadata, configure parameters that are prefixed with x-oss-meta-*.

    --object-acl

    string

    The access control list (ACL) for the object.

    --server-side-data-encryption

    string

    The server-side encryption algorithm to use when you create an object.

    --server-side-encryption

    string

    The server-side encryption method.

    --server-side-encryption-key-id

    string

    The ID of the customer master key (CMK) managed by KMS.

    --storage-class

    string

    The storage class of the object.

    --tagging

    string

    The tags of the object. You can specify multiple tags. Example: TagA=A&TagB=B.

    Note

    • The put-object command corresponds to the PutObject API operation. For more information about the parameters in the PutObject operation, see PutObject.

    • For more information about supported global command-line options, see Global command-line options.

    Examples

    • Upload an object from a string.

      ossutil api put-object --bucket examplebucket --key exampleobject --body "hi oss"

    • Upload an object from a local file.

      ossutil api put-object --bucket examplebucket --key exampleobject --body file://uploadFile

    • Upload an object from a string and add custom metadata.

      ossutil api put-object --bucket examplebucket --key exampleobject  --metadata user=aliyun --metadata email=ali***@aliyuncs.com --body "hi oss"

    • Upload an object from a string and specify tags for the object.

      ossutil api put-object --bucket examplebucket --key exampleobject --body "hi oss" --tagging "TagA=A&TagB=B"

    • Upload an object from a string and specify the ACL and storage class of the object.

      ossutil api put-object --bucket examplebucket --key exampleobject --body "hi oss" --object-acl private --storage-class IA

    • Upload an object from a string and specify the server-side encryption method for the object.

      ossutil api put-object --bucket examplebucket --key exampleobject --body "hi oss" --server-side-encryption KMS --server-side-data-encryption SM4 --server-side-encryption-key-id 9468da86-3509-4f8d-a61e-6eab1eac****

    • Upload an object from a string and prevent the object from overwriting an existing object that has the same name.

      ossutil api put-object --bucket examplebucket --key exampleobject --body "hi oss" --forbid-overwrite true

    • Upload an object from a string and specify the object's caching behavior.

      ossutil api put-object --bucket examplebucket --key exampleobject --body "hi oss" --cache-control no-cache

    • Upload an object from a string and specify the name of the object when it is downloaded.

      ossutil api put-object --bucket examplebucket --key exampleobject --body "hi oss" --content-disposition "attachment;filename=oss_download.jpg"