All Products
Search

This Product

    Object Storage Service:cp (copy objects)

    Document Center

    Object Storage Service:cp (copy objects)

    Last Updated:Mar 31, 2026

    Use the cp command to copy objects from a source bucket to a destination bucket in the same region, or to another directory within the same bucket.

    Usage notes

    • The cp command does not support cross-account or cross-region copy operations. To copy or migrate objects across accounts or regions, use Data Online Migration.

    • This command copies only complete objects. It does not support copying incomplete parts from a multipart upload.

    • Starting with ossutil 1.6.16, you can use ossutil as the binary name without renaming it. In earlier versions, you must rename the binary according to your operating system. For more information, see Get started with ossutil.

      Permissions

      By default, only the Alibaba Cloud account has permission to perform all API operations. To run this command, a RAM user or RAM role must be granted the required permission by the Alibaba Cloud account or an administrator through a RAM Policy or Bucket Policy.

      API action

      Description

      oss:GetObject

      Copies an object within the same bucket or between different buckets in the same region.

      oss:PutObject

      oss:GetObjectVersion

      Optional. This permission is required to copy a specific version of an object.

      oss:GetObjectTagging

      Optional. These permissions are required if the copy operation involves object tagging.

      oss:PutObjectTagging

      oss:GetObjectVersionTagging

      Optional. This permission is required if the copy operation involves tags of a specific object version.

      kms:GenerateDataKey

      Optional. These permissions are required if the copy operation involves server-side encryption with KMS.

      kms:Decrypt

      Command syntax

      ossutil cp cloud_url cloud_url [options]

      The following table describes the parameters and options.

      Parameter

      Description

      cloud_url

      The source and destination OSS object paths. The format is oss://bucketname/objectname. For example, to copy the source object srcobject.jpg to the destination object destobject.jpg in the same bucket named examplebucket, set the source path to oss://examplebucket/srcobject.jpg and the destination path to oss://examplebucket/destobject.jpg.

      -r, --recursive

      Performs a recursive operation. When specified, ossutil applies the operation to all objects that match the specified prefix. Otherwise, the operation applies only to the single specified object.

      -f --force

      Forces the operation without a confirmation prompt.

      -u, --update

      Copies an object only if the destination object does not exist or if the last modified time of the source object is later than that of the destination object.

      --disable-ignore-error

      Does not ignore errors during batch operations.

      --only-current-dir

      Copies only the objects in the current directory and ignores subdirectories.

      -bigfile-threshold

      The size threshold for a resumable copy. Unit: bytes.

      Default value: 100 MB

      Valid values: 0 to 9223372036854775807

      --part-size

      The size of each part in a multipart copy operation. Unit: bytes. By default, ossutil automatically calculates an appropriate part size based on the object size.

      Valid values: 1 to 9223372036854775807

      --checkpoint-dir

      The directory that stores the checkpoint information for a resumable copy. If a resumable copy fails, ossutil automatically creates a directory named .ossutil_checkpoint to record checkpoint information. This directory is deleted after the resumable copy is successful. If you specify this option, ensure the specified directory is deletable.

      --encoding-type

      Specify url to URL-encode the object names. If this option is not specified, object names are not encoded.

      --include

      Includes all objects that match the specified pattern.

      --exclude

      Excludes all objects that match the specified pattern.

      --meta

      Sets the metadata for the object. The format is header:value#header:value. Example: Cache-Control:no-cache#Content-Encoding:gzip. For more information about metadata, see set-meta (Manage object metadata).

      --acl

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

      • default (default): The object inherits the ACL of the bucket.

      • private: Only the bucket owner has read and write permissions on the object. Other users cannot access the object.

      • public-read: Only the bucket owner has write permission on the object. All other users, including anonymous users, have read-only permission. This may cause data leaks and unexpected charges. If a malicious user writes illegal information, you may be held legally liable. We do not recommend that you grant this permission unless necessary.

      • public-read-write: All users, including anonymous users, have read and write permissions on the object. This may cause data leaks and unexpected charges. Use this permission with caution.

      --disable-crc64

      Disables CRC-64 data integrity checking. By default, CRC-64 is enabled for data transfer in ossutil.

      --payer

      The payer for the request. To charge the requester for access fees (such as data transfer and requests), set this option to requester.

      -j, --jobs

      The number of concurrent tasks for batch operations. Default value: 3. Valid values: 1 to 10000.

      --parallel

      The number of concurrent tasks for a single-object operation. Valid values: 1 to 10000. If this option is not specified, ossutil determines the value based on the operation type and object size.

      --version-id

      Copies a specific version of an object. This option is available only for buckets with versioning enabled.

      --start-time

      A Unix timestamp. If specified, objects last modified before this time are ignored.

      Note

      This parameter is supported only in ossutil 1.7.18 and later. For more information about how to upgrade ossutil, see update (Upgrade ossutil).

      --end-time

      A Unix timestamp. If specified, objects last modified after this time are ignored.

      Note

      • If you specify both start-time and end-time, the command copies only objects whose last modified time is between the specified start and end times.

      • This parameter is supported only in ossutil 1.7.18 and later. For more information about how to upgrade ossutil, see update (Upgrade ossutil).

      For more information about other common options for this command, see common options.

      If the default concurrency does not meet your performance requirements, you can adjust the -j, --jobs and --parallel options to tune the performance. By default, ossutil calculates the value of parallel based on the object size. When you transfer large objects in batches, the actual concurrency is the value of jobs multiplied by the value of parallel.

      • If the resources, such as network, memory, and CPU, of the ECS instance or server that runs the command are limited, we recommend that you decrease the concurrency to a value of less than 100. If resources are not fully utilized, you can increase the concurrency as needed.

      • An excessively high concurrency may degrade performance or even cause EOF errors due to thread switching overhead and resource competition. Adjust the -j, --jobs and --parallel options based on your machine's resources. When you perform stress testing, we recommend that you start with a low concurrency and gradually increase it to find the optimal value.

      Examples

      The following examples use a Linux system. Modify the parameters based on your operating system and actual environment. The examples assume the following:

      • Source bucket: examplebucket1

      • Source directory 1 in the source bucket: srcfolder1

      • Source directory 2 in the source bucket: srcfolder2

      • Destination bucket: examplebucket2

      • Destination directory in the destination bucket: desfolder

      Copy a single object

      Copy an object from one directory to another directory in the same bucket and rename the object to example.txt.

      ossutil cp oss://examplebucket1/srcfolder1/examplefile.txt oss://examplebucket1/srcfolder2/example.txt

      Copy multiple objects in a batch

      The behavior of a batch copy changes depending on whether the source path ends with a forward slash (/). If the path does not end with /, all objects with that prefix are copied. If the path ends with /, only the objects directly within that directory are copied.

      Assume that the srcfolder1 directory in the source bucket examplebucket1 contains the following objects:

      srcfolder1/exampleobject1.txt
srcfolder1/exampleobject2.png
srcfolder1/dir1/
srcfolder1/dir1/exampleobject3.jpg
srcfolder1/dir2/
srcfolder1/dir2/exampleobject4.jpg

      • The source path does not end with a forward slash (/)

        ossutil cp oss://examplebucket1/srcfolder1  oss://examplebucket2 -r

        After the copy is complete, the following objects are present in the destination bucket examplebucket2:

        srcfolder1/exampleobject1.txt
srcfolder1/exampleobject2.png
srcfolder1/dir1/
srcfolder1/dir1/exampleobject3.jpg
srcfolder1/dir2/
srcfolder1/dir2/exampleobject4.jpg

      • The source path ends with a forward slash (/)

        ossutil cp oss://examplebucket1/srcfolder1/  oss://examplebucket2 -r

        After the copy is complete, the following objects are present in the destination bucket examplebucket2:

        exampleobject1.txt
exampleobject2.png
dir1/
dir1/exampleobject3.jpg
dir2/
dir2/exampleobject4.jpg

      • Perform an incremental copy

        During a batch copy, if you specify the --update option, ossutil copies an object only if the destination object does not exist or if the last modified time of the source object is later than that of the destination object. The command is as follows:

        ossutil cp oss://examplebucket1/srcfolder1/ oss://examplebucket2/path2/ -r --update

        You can use this option to resume a failed batch copy operation by skipping objects that have already been successfully copied.

      • Copy only objects in the current directory and ignore subdirectories

        ossutil cp oss://examplebucket1/srcfolder1/ oss://examplebucket1/srcfolder2/ --only-current-dir -r

      Copy objects within a specified time range

      Copy only the objects in srcfolder1 that were last modified between 10:09:18 on October 31, 2023 (UTC+8) and 12:55:58 on October 31, 2023 (UTC+8).

      ossutil cp -r oss://examplebucket1/srcfolder1/ oss://examplebucket2/path2/ --start-time 1698718158 --end-time 1698728158

      Copy objects with conditions

      Use the --include and --exclude options to copy only objects that meet specific conditions.

      • Copy all objects that are not in JPG format

        ossutil cp oss://examplebucket1/srcfolder1/ oss://examplebucket2/desfolder/ --exclude "*.jpg" -r

      • Copy all objects whose names contain abc but are not in JPG or TXT format

        ossutil cp oss://examplebucket1/srcfolder1/ oss://examplebucket2/desfolder/ --include "*abc*" --exclude "*.jpg" --exclude "*.txt" -r

      Copy and modify object metadata

      Use the --meta option to modify the object metadata. The format is header:value#header:value....

      ossutil cp oss://examplebucket1/examplefile.txt oss://examplebucket1/ --meta=Cache-Control:no-cache

      Copy with Requester Pays

      Copy an object from a source bucket to a destination bucket and specify the Requester Pays mode.

      ossutil cp oss://examplebucket1/examplefile.txt oss://examplebucket2/desfolder/  --payer=requester

      Copy and change storage class

      When you overwrite an object, you can add the --meta option to change its storage class. Valid values:

      • Standard

      • Infrequent Access

      • Archive Storage

      • Cold Archive

      • Deep Cold Archive

      For more information about storage classes, see Storage classes.

      Important

      When you use the --meta option to modify the storage class, existing custom file metadata is overwritten by default. To preserve this metadata during the modification, use ossutil 2.0.

      • Change the storage class of a specific object to Archive Storage

        ossutil cp oss://examplebucket1/srcfolder1/examplefile.txt oss://examplebucket1/srcfolder1/examplefile.txt --meta X-oss-Storage-Class:Archive

      • Change the storage class of all objects in a specified folder to Standard

        ossutil cp oss://examplebucket1/srcfolder1/ oss://examplebucket1/srcfolder1/ --meta X-oss-Storage-Class:Standard -r
      Important

      • When you use the cp command to change the storage class of an object, you are charged for PUT requests based on the source storage class of the object. The fees are billed to the destination bucket.

      • If you convert an object to the Infrequent Access, Archive Storage, Cold Archive, or Deep Cold Archive storage class and the object is stored for less than the minimum storage duration, an early deletion fee is charged. For more information, see Storage fees.

      • To convert an object from Archive Storage, Cold Archive, or Deep Cold Archive to Standard or Infrequent Access by using the cp command, you must first restore the object by using the restore (restore an object) command. After the object is restored, you can use the cp command to change its storage class. If real-time access of Archive objects is enabled, you can change the storage class of Archive Storage objects without restoring them.

      • When you use the cp command to change the storage class of an object larger than 100 MB, ossutil calculates a suitable part size based on the object size by default. If the automatic part size does not meet your needs, you can use the --part-size option to specify a part size. Make sure that the number of parts does not exceed 10,000.

      Copy and set tags

      When you overwrite an object, you can add the --tagging option to add or modify object tags. Separate multiple tags with ampersands (&). The command is as follows:

      ossutil cp oss://examplebucket1/examplefile.txt oss://examplebucket1/ --tagging "abc=1&bcd=2&……"

      For more information about object tagging, see object-tagging (Object tagging).

      Copy with server-side encryption

      You can specify a server-side encryption method to encrypt an object when you copy it to a bucket. For more information about server-side encryption, see Server-side encryption.

      • Copy an object and specify AES256 as the encryption method

        ossutil cp oss://examplebucket1/examplefile.txt oss://examplebucket1/srcfolder2/ --meta=x-oss-server-side-encryption:AES256

      • Copy an object and specify KMS as the encryption method

        ossutil cp oss://examplebucket1/examplefile.txt oss://examplebucket2/desfolder/ --meta=x-oss-server-side-encryption:KMS
        Important

        When you use KMS for encryption, OSS calls KMS to generate a master key for the object. This action incurs a fee for KMS API calls. For more information, see KMS billing.

      • Copy an object and specify the CMK ID for KMS encryption

        ossutil cp oss://examplebucket1/examplefile.txt oss://examplebucket2/desfolder/ --meta=x-oss-server-side-encryption:KMS#x-oss-server-side-encryption-key-id:7bd6e2fe-cd0e-483e-acb0-f4b9e1******

      Restore a previous object version

      After you enable versioning for a bucket, overwritten and deleted objects are saved as previous versions. You can add the --version-id option to the cp command to restore a previous version.

      First, use the ls --all-versions command to retrieve all version IDs of the object. Then, use the --version-id option to copy a specific version.

      Note

      The --version-id option is available only for buckets with versioning enabled. For more information about the command to enable versioning for a bucket, see bucket-versioning (Versioning).

      ossutil cp oss://examplebucket1/examplefile.txt oss://examplebucket2/ --version-id  CAEQARiBgID8rumR2hYiIGUyOTAyZGY2MzU5MjQ5ZjlhYzQzZjNlYTAyZDE3MDRk

      Cross-account copy

      Use the -e, -i, and -k common options to copy the srcobject.png object from the root directory of the source bucket examplebucket in the China (Shanghai) region that belongs to another Alibaba Cloud account to the destination bucket destbucket.

      Note

      You must specify the endpoint for the region where the bucket is located. For more information, see Regions and Endpoints.

      ossutil cp oss://examplebucket/srcobject.png  oss://destbucket  -e oss-cn-shanghai.aliyuncs.com -i yourAccessKeyID  -k yourAccessKeySecret
      Security tip: Including an AccessKey on the command line is a security risk. For automated or long-term tasks, we recommend that you create a RAM role for the source account and grant the destination account permissions to assume the RAM role for more secure cross-account access.