All Products
Search

This Product

    Object Storage Service:copy-object

    Document Center

    Object Storage Service:copy-object

    Last Updated:Jul 03, 2025

    The copy-object command is used to copy objects that are stored in the same bucket or different buckets in the same region.

    Notes

    • To recover a previous version of an object to the current version, you can copy the previous version of the object to the bucket in which the object is stored. OSS then stores the previous version of the object as the current version.

    • If you copy objects within the same bucket, no limit is imposed on the size of the object that is copied. If you copy objects between buckets in the same region, we recommend that you call this operation to copy objects smaller than 1 GB. To copy objects larger than 1 GB, you can execute the upload-part-copy command.

    • If the source object is a symbolic link, only the symbolic link is copied. The object to which the symbolic link points is not copied.

    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 Policy.

    API

    Action

    Definition

    CopyObject

    oss:GetObject

    Copies objects within a bucket or between buckets in the same region.

    oss:PutObject

    oss:GetObjectVersion

    If you specify the source object version through versionId, this permission is also required.

    oss:GetObjectTagging

    If you copy object tags through x-oss-tagging, these permissions are required.

    oss:PutObjectTagging

    oss:GetObjectVersionTagging

    If you specify the tags of a specific version of the source object through versionId, this permission is also required.

    kms:GenerateDataKey

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

    kms:Decrypt

    Syntax

    ossutil api copy-object --bucket value --key value --copy-source value [flags]

    Parameter

    Type

    Description

    --bucket

    string

    Name of the bucket.

    --key

    string

    Full path of the object.

    --forbid-overwrite

    string

    Specifies whether the CopyObject operation is allowed to overwrite existing objects that have the same name as the objects that you intend to copy.

    --copy-source

    string

    Address used to access the source object. format: bucket/UrIEncode(key). You must have the permissions to read the source object. The name of the source object must be URL-encoded.

    --copy-source-if-match

    string

    If the ETag value of the source object is the same as the ETag value specified in the request, OSS copies the object. Otherwise, OSS returns the HTTP status code 412 (PreconditionFailed).

    --copy-source-if-modified-since

    string

    Condition of object transfer. If the specified time is earlier than the actual modified time of the object, the system transfers the object and returns 200 OK. Otherwise, the system returns 304 Not Modified.

    --copy-source-if-none-match

    string

    Condition of object transfer. If the specified ETag value does not match the ETag value of the source object, OSS transfers the object and returns 200 OK. Otherwise, OSS returns 304 Not Modified.

    --copy-source-if-unmodified-since

    string

    Condition of object transfer. If the specified time is the same as or later than the actual time of modification, OSS transfers the object and returns 200 OK. Otherwise, OSS returns 412 Precondition Failed.

    --metadata

    stringArray

    User metadata of the object in the key=value format. To specify custom metadata, you must configure parameters prefixed with x-oss-meta-*.

    --metadata-directive

    string

    Method used to configure the metadata of the destination object.

    --object-acl

    string

    Specifies the access control list (ACL) of the object.

    --server-side-encryption

    string

    Method used to encrypt objects on the OSS server.

    --server-side-encryption-key-id

    string

    ID of the customer master key (CMK) managed by Key Management Service (KMS).

    --storage-class

    string

    Storage class of the object.

    --tagging

    string

    Tags of the object.

    --tagging-directive

    string

    Method used to add tags to the destination object.

    Note

    • The copy-object command corresponds to the CopyObject API operation. For more information about the parameters within, see CopyObject.

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

    Examples

    • Copy srcObject from srcBucket to examplebucket as exampleobject.

      ossutil api copy-object --bucket examplebucket --key exampleobject --copy-source /srcBucket/srcObject

    • Copy srcObject from examplebucket as exampleobject.

      ossutil api copy-object --bucket examplebucket --key exampleobject --copy-source /examplebucket/srcObject

    • Copy srcObject from examplebucket as exampleobject and display the result in the JSON format.

      ossutil api copy-object --bucket examplebucket --key exampleobject --copy-source /examplebucket/srcObject --output-format json

    • Copy srcObject from examplebucket as exampleobject and display the result in the YAML format.

      ossutil api copy-object --bucket examplebucket --key exampleobject --copy-source /examplebucket/srcObject --output-format yaml

    • Copy srcObject from examplebucket as exampleobject and forbid exampleobject from overwriting the existing object that has the same name.

      ossutil api copy-object --bucket examplebucket --key exampleobject --copy-source /examplebucket/srcObject --forbid-overwrite true

    • Copy srcObject from examplebucket as exampleobject if the ETag value of srcObject equals 123.

      ossutil api copy-object --bucket examplebucket --key exampleobject --copy-source /examplebucket/srcObject --copy-source-if-match 123

    • Copy srcObject from examplebucket as exampleobject if the modification time of srcObject is earlier than Mon, 11 May 2020 08:16:23 GMT.

      ossutil api copy-object --bucket examplebucket --key exampleobject --copy-source /examplebucket/srcObject --copy-source-if-unmodified-since "Mon, 11 May 2020 08:16:23 GMT"

    • Copy srcObject from examplebucket as exampleobject. The metadata specified in the request is used instead of the metadata of srcObject.

      ossutil api copy-object --bucket examplebucket --key exampleobject --copy-source /examplebucket/srcObject --metadata-directive REPLACE --metadata user=aliyun --metadata email=ali***@aliyuncs.com

    • Copy srcObject from examplebucket as exampleobject. The tags specified in the request are added to exampleobject.

      ossutil api copy-object --bucket examplebucket --key exampleobject --copy-source /examplebucket/srcObject --tagging-directive Replace --tagging "TagA=A&TagB=B"

    • Copy srcObject from examplebucket as exampleobject and specify the ACL and storage class of the object.

      ossutil api copy-object --bucket examplebucket --key exampleobject --copy-source /examplebucket/srcObject --object-acl private --storage-class IA