All Products
Search

This Product

    Object Storage Service:put-object

    Document Center

    Object Storage Service:put-object

    Last Updated:Dec 06, 2025

    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 Policy or Bucket policies.

    API

    Action

    Definition

    PutObject

    oss:PutObject

    Uploads an object.

    oss:PutObjectTagging

    When uploading an object, if you specify object tags through x-oss-tagging, this permission is required.

    kms:GenerateDataKey

    When uploading an object, if the object metadata contains X-Oss-Server-Side-Encryption: KMS, these two permissions are required.

    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 web page caching behavior of the object.

    --content-disposition

    string

    Specify the name of the object to upload.

    --content-encoding

    string

    The encoding format of the object content.

    --expires

    string

    The expiration time.

    --forbid-overwrite

    boolean

    Specifies 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) of 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) that is managed by Key Management Service (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 web page caching behavior when the object is downloaded.

      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"