The cp command is used to upload, download, or copy objects.

Note The commands described in this topic apply to Linux. To use the commands in other systems, replace ./ossutil in the command with the actual executable program name. For example, you can use the help command in 32-bit Windows systems by running ossutil32.exe help.

Command syntax

  • Upload objects
    ./ossutil cp file_url cloud_url  [-r] [-f] [-u] [--enable-symlink-dir] [--disable-all-symlink] [--only-current-dir] [--output-dir=odir] [--bigfile-threshold=size] [--checkpoint-dir=cdir] [--snapshot-path=sdir] [--payer requester] [--tagging]
  • Download objects
    ./ossutil cp cloud_url file_url  [-r] [-f] [-u] [--only-current-dir] [--output-dir=odir] [--bigfile-threshold=size] [--checkpoint-dir=cdir] [--range=x-y] [--payer requester] [--version-id versionId]
  • Copy objects
    ./ossutil cp cloud_url cloud_url [-r] [-f] [-u] [--only-current-dir] [--output-dir=odir] [--bigfile-threshold=size] [--checkpoint-dir=cdir] [--payer requester] [--version-id versionId] [--tagging]

Examples for object upload

  • Upload a single object
    ./ossutil cp a.txt oss://bucket/path
  • Upload a single object and specify the --meta option.
    When you upload an object, you can use the --meta option to configure object metadata in the header:value#header:value... format. Run the following command to upload the a.txt object and configure its metadata:
    ./ossutil cp a.txt oss://bucket/path --meta=Cache-Control:no-cache#Content-Encoding:gzip
    Note For more information about how to configure metadata, see set-meta.
  • Upload a folder
    You can add the -r option to the cp command to upload a folder to OSS.
    ./ossutil cp -r dir oss://bucket/path/
    Note If the object to upload is a symbolic link that points to a local folder, you must add a forward slash (/) to the symbolic link when you use the cp command to upload the object.
    ./ossutil cp -r symbolic_link/ oss://bucket/path/
  • Upload an object or a folder and configure the maximum upload speed
    When you upload an object or a folder, you can use the --maxupspeed option to configure the maximum upload speed measured in KB/s. The default value is 0, which indicates that the maximum upload speed is unlimited.
    • Upload an object and set the maximum upload speed to 1 MB/s
      ./ossutil cp a.jpg oss://bucket/path --maxupspeed 1024
    • Upload a folder and set the maximum upload speed to 1 MB/s
      ./ossutil cp -r dir oss://bucket/path --maxupspeed 1024
  • Upload multiple objects that meet specified conditions

    When you copy multiple objects, you can add the --include and --exclude options to the cp command to specify conditions for selecting objects.

    The --include and --exclude options support the following formats:
    • *: matches all characters. For example, *.txt specifies any TXT objects.
    • ?: matches any single character. For example, abc?.jpg specifies all JPG objects whose names begin with abc and are followed by any single character, such as abc1.jpg.
    • [sequence]: matches any characters in a sequence. For example, abc[1-5].jpg specifies the objects whose names begin with abc and are followed by a number contained in sequence [1-5]. The objects include abc1.jpg, abc2.jpg, abc3.jpg, abc4.jpg, and abc5.jpg.
    • [! sequence]: matches any characters that are not in a sequence. For example, abc[! 0-7].jpg specifies the objects whose names begin with abc and are not followed by a number contained in the sequence [0-7], such as abc8.jpg.
    Note
    • Names that include directories, such as --include "/usr/test/.jpg", are not supported.
    • To specify the --include and --exclude options, you must also specify the --recursive (-r) option.
    • One rule can contain multiple conditions specified by include and exclude. If these conditions are set, ossutil reads each rule sequentially from left to right to obtain the final matching results.
      If the test.txt object exists in a valid folder, results are generated based on different matching rules.
      • Rule 1: --include "*test*" --exclude "*.txt" . When ossutil reads the --include "*test*" condition, the test.txt object matches the condition. When ossutil reads the --exclude "*.txt" condition, the test.txt object is excluded because it is in the TXT format. The final matching results exclude the test.txt object.
      • Rule 2: --exclude "*.txt" --include "*test*". When ossutil reads the --exclude "*.txt" condition, the test.txt object is excluded. When ossutil reads the --include "*test*" condition, the test.txt object matches the condition because its name contains test. The final matching results include the test.txt object.
      • Rule 3: --include "*test*" --exclude "*.txt" --include "te? t.txt" . When ossutil reads the --include "*test*" condition, the test.txt object matches the condition. When ossutil reads the --exclude "*.txt"condition, the test.txt object is excluded because it is in the TXT format. When ossutil reads the --include "te? t.txt" condition, the test.txt object matches the condition. The final matching results include the test.txt object.
    Examples:
    • Upload all objects that are in the TXT format
      ./ossutil cp dir/ oss://my-bucket/path --include "*.txt" -r
    • Upload all objects that contain abc in their names and are not in the JPG or TXT format.
      ./ossutil cp dir/ oss://my-bucket/path --include "*abc*" --exclude "*.jpg" --exclude "*.txt" -r
  • Upload an object and configure its storage class
    When you upload an object, you can use the --meta option to configure the storage class of the object.
    • Upload an object and set its storage class to IA
      ./ossutil cp dir/sys.log  oss://my-bucket/path --meta X-oss-Storage-Class:IA
    • Upload a folder and set the storage class of all objects in the folder to IA
      ./ossutil cp dir/ oss://my-bucket/path --meta X-oss-Storage-Class:IA -r
  • Upload an object and specify the server-side encryption method
    You can specify the server-side encryption method when you upload an object and store the encrypted object in a bucket. For more information about server-side encryption, see Server-side encryption.
    • Upload an object and set the server-side encryption method to AES-256
      ./ossutil cp a.txt oss://my-bucket/path --meta=x-oss-server-side-encryption:AES256
    • Upload an object and set the server-side encryption method to KMS
      ./ossutil cp a.txt oss://my-bucket/path --meta=x-oss-server-side-encryption:KMS

      When you use KMS to encrypt an object, OSS creates a customer master key (CMK) in the KMS console for the object. This will incur a small amount of fees whenever the KMS API operation is called.

  • Upload an object and specify the object tag
    ./ossutil cp a.txt oss://my-bucket/path --tagging "abc=1&bcd=2&……"

    For more information about object tagging, see object-tagging.

  • Upload a folder without uploading the existing objects

    If you specify the --update (abbreviated as -u) option when you upload multiple objects, ossutil only uploads objects that do not exist in the destination bucket or objects that were modified more recently than their corresponding objects in the destination bucket. The command is as follows:

    ./ossutil cp -r dir oss://bucket1/path/ -u

    This option can be used to perform incremental upload on objects that have not been successfully uploaded.

  • Upload a folder and generate snapshot information

    If you specify the --snapshot-path option when you upload multiple objects, ossutil takes a snapshot of the upload and stores the snapshot information in a specified directory. The next time the objects are uploaded while this option is specified, ossutil will read the snapshot information from the specified directory and perform an incremental upload. The command is as follows:

    ./ossutil cp -r dir/ oss://bucket1/path/ --snapshot-path=path                                
    Notice
    • The --snapshot-path option is used in certain scenarios to accelerate the incremental upload or download of objects. This option cannot be used to copy objects. This option can be used when the number of objects is large and no other users modify the corresponding objects in OSS between the two uploads.
    • The --snapshot-path option records the local lastModifiedTime of uploaded or downloaded objects and compares it to the lastModifiedTime of objects currently pending upload or download to determine which objects can be skipped. When using this option, ensure that the corresponding objects in OSS are not modified between the two uploads or downloads. In other scenarios where objects are updated in OSS between the two uploads or downloads, use the --update option to perform incremental upload or download on objects.
    • ossutil does not automatically delete snapshot information from the directory specified by snapshot-path. You can remove the directory if the snapshot information is no longer needed.
    • Additional overheads are required to read and write snapshot information. We recommend that you do not use this option in the following scenarios: The number of objects to upload or download is small. The network is properly connected. Other users need to perform operations on those objects. In this case, you can use the --update option to perform incremental upload or download.
    • The --update and --snapshot-path options can be used together. ossutil first uses the --snapshot-path option to determine whether to skip the upload or download of an object. If the upload or download is not skipped by --snapshot-path, ossutil then uses the --update option to determine whether to skip the upload or download of the object.
  • Upload an object to a bucket that has pay-by-requester enabled
    ./ossutil cp dir/test.mp4 oss://payer/ --payer=requester
  • Upload only objects in the current folder and ignore subdfolders
    ./ossutil cp dir/ oss://bucket1/path/ --only-current-dir -r
  • Do not generate an object for an uploaded folder
    ./ossutil cp dir/ oss://bucket1/path/ --disable-dir-object -r
    The OSS folder is simulated with an object that is 0 KB in size and whose name ends with a forward slash (/). If you specify the --disable-dir-object option when you upload objects, ossutil does not generate an object for the folder to which the objects belong. However, you can view the corresponding folder structure in the OSS console. If you delete objects from the folder, the folder is also deleted.
  • Upload objects in the subdirectory to which the symbolic link points
    ./ossutil cp dir/ oss://bucket1/path/ --enable-symlink-dir -r
  • All objects in the subdirectory to which the symbolic link points and the subdirectory to which the symbolic link points are ignored during object upload.
    ./ossutil cp dir/ oss://bucket1/path/ -r --disable-all-symlink

Examples for object download

  • Download a single object
    ./ossutil cp oss://my-bucket/path/test1.txt /dir
  • Download parts of an object within a specified range

    You can use the --range option to download parts of an object within a specified range.

    For example, download the 10th to 20th characters from the test1.txt object as a file to your local device.
    ./ossutil cp oss://my-bucket/path/test1.txt /dir  --range=10-20
    Succeed: Total num: 1, size: 11. OK num: 1(download 1 objects).
    0.290769(s) elapsed
  • Download an object from a bucket that has pay-by-requester enabled
    ./ossutil cp oss://payer/test.mp4 dir/ --payer=requester
  • Download a folder
    ./ossutil cp -r oss://my-bucket/path/ dir/ 
  • Download a folder and specify the --update option
    If you specify the --update option when you download multiple objects, ossutil only downloads objects that do not exist in the destination bucket or objects that were modified more recently than their corresponding objects in the destination bucket. The command is as follows:
    ./ossutil cp -r oss://bucket/path/  dir/  --update                           
    This option can be used to perform incremental download on objects that have not been successfully downloaded.
  • Download a folder and generate snapshot information

    If you specify the --snapshot-path option when you download multiple objects, ossutil takes a snapshot of the download and stores the snapshot information in a specified directory. The next time the objects are downloaded while this option is specified, ossutil will read the snapshot information from the specified directory and perform an incremental download. For more information, see --snapshot-path.

    ./ossutil cp -r oss://bucket1/path/ dir/ --snapshot-path=path                                
  • Download multiple objects that meet specified conditions
    When you download multiple objects, you can use --include and --exclude options to specify conditions for selecting objects. For more information, see the --include and --exclude section in this topic.
    • Download all objects that are not in the JPG format
      ./ossutil cp oss://my-bucket/path/ dir/ --exclude "*.jpg" -r
    • Download all objects that contain abc in their names and are not in the JPG or TXT format
      ./ossutil cp oss://my-bucket1/path/ dir/ --include "*abc*" --exclude "*.jpg" --exclude "*.txt" -r
  • Download a specified version of an object from a versioning-enabled bucket
    ./ossutil cp oss://bucket1/test.jpg dir/ --version-id  CAEQARiBgID8rumR2hYiIGUyOTAyZGY2MzU5MjQ5ZjlhYzQzZjNlYTAyZDE3MDRk
    To use the --version-id option, you must run the ls --all-versions command to obtain version IDs of the object.
    Note The --version-id option can be used only for objects in versioning-enabled buckets. For more information about the command used to enable versioning on a bucket, see bucket-versioning.
  • Download only objects in the current directory and ignore subdirectories
    ./ossutil cp oss://bucket1/path/ dir/ --only-current-dir -r

Examples for copying objects

Only objects can be copied. Parts cannot be copied. You cannot copy objects across regions.

  • Copy a single object
    ./ossutil cp oss://bucket/path1/a oss://bucket/path2/                                 
  • Copy and rename a single object
    ./ossutil cp oss://bucket/path1/a oss://bucket/path2/b                           
  • Copy multiple objects that meet specified conditions
    When you copy multiple objects, you can use --include and --exclude options to specify conditions for selecting objects. For more information, see the --include and --exclude section in this topic.
    • Copy all objects that are not in the JPG format
      ./ossutil cp oss://my-bucket1/path/ oss://my-bucket2/path --exclude "*.jpg" -r
    • Copy all objects that contain abc in their names and are not in the JPG or TXT format.
      ./ossutil cp oss://my-bucket1/path/ oss://my-bucket2/path/ --include "*abc*" --exclude "*.jpg" --exclude "*.txt" -r
  • Copy an object and modify its storage class
    • Set the storage class of an existing object to Archive
      ./ossutil cp oss://my-bucket/path/0104_6.jpg oss://my-bucket/path/0104_6.jpg --meta X-oss-Storage-Class:Archive
    • Set the storage class of all objects in an existing folder to Standard
      ./ossutil cp oss://my-bucket/path/ oss://my-bucket/path/ --meta X-oss-Storage-Class:Standard -r
      Notice
      • You cannot use the cp command to convert the storage class of an object from Archive or Clod Archive to any other storage class. You must first use the restore command to restore the object to the readable state, and then use the cp command to modify its storage class.
      • When you run the cp command to overwrite an object, it is considered overwritten and fees may be incurred. If an object of the IA or Archive and Cold Archive storage class is overwritten within the minimum storage duration, early deletion fees will be incurred. For more information, see Billing items and methods.
  • Copy an object and specify the server-side encryption method
    You can specify the server-side encryption method when you copy an object and store the encrypted object in a bucket. For more information about server-side encryption, see Server-side encryption.
    • Copy an object and set the server-side encryption method to AES-256
      ./ossutil cp oss://bucket/path1/a oss://bucket/path2/ --meta=x-oss-server-side-encryption:AES256
    • Copy an object and set the server-side encryption method to KMS
      ./ossutil cp oss://bucket/path1/a oss://bucket/path2/ --meta=x-oss-server-side-encryption:KMS

      When you use KMS to encrypt an object, OSS creates a customer master key (CMK) in the KMS console for the object. This will incur a small amount of fees whenever the KMS API operation is called.

  • Copy a single object and specify the --meta option
    When you copy an object, you can use the --meta option to configure object metadata in header:value#header:value... format.
    ./ossutil cp oss://bucket/path1/a oss://bucket/path2/ --meta=Cache-Control:no-cache
  • Copy an object and specify the object tag
    ./ossutil cp oss://bucket1/path1/a oss://bucket2/path2/ --tagging "abc=1&bcd=2&……"
  • Copy multiple objects between different buckets within the same region
    You can add the -r option to the cp command to copy multiple objects between different buckets within the same region.
    ./ossutil cp oss://your_src_bucket/path1/ oss://your_dest_bucket/path2/ -r                                   
  • Perform incremental copy on objects between different buckets within the same region
    If you specify the --update option when you copy multiple objects, ossutil only copies objects that do not exist in the destination bucket or objects that were modified more recently than their corresponding objects in the destination bucket. The command is as follows:
    ./ossutil cp oss://your_src_bucket/path1/ oss://your_dest_bucket/path2/ -r --update
    This option can be used to perform incremental copy on objects that have not been successfully copied.
  • Copy an object from a bucket that has pay-by-requester enabled to a common bucket
    ./ossutil cp oss://payer/test.mp4 oss://my-bucket/path  --payer=requester
  • Copy an object from a common bucket to a bucket that has pay-by-requester enabled
    ./ossutil cp oss://my-bucket/path/test.mp4 oss://payer/ --payer=requester
  • Copy a specified version of an object in a versioning-enabled bucket
    ./ossutil cp oss://bucket1/test.jpg oss://bucket2/ --version-id  CAEQARiBgID8rumR2hYiIGUyOTAyZGY2MzU5MjQ5ZjlhYzQzZjNlYTAyZDE3MDRk
    To use the --version-id option, you must run the ls --all-versions command to query version IDs of the object.
    Note The --version-id option can be used only for objects in versioning-enabled buckets. For more information about the command used to enable versioning on a bucket, see bucket-versioning.
  • Copy only objects in the current directory and ignore subdirectories
    ./ossutil cp oss://bucket1/path oss://bucket2/path --only-current-dir -r

Performance optimization

You can add the --jobs and --parallel options to the cp command to specify the number of concurrent operations. If the default number of concurrent operations set by ossutil does not meet your performance requirements, you can modify the values of these two options to adjust the performance.
  • The --jobs option specifies the number of concurrent jobs when multiple objects are uploaded, downloaded, or copied.
  • The --parallel option specifies the number of concurrent operations performed on a large object during multipart upload, download, or copy.

By default, ossutil calculates the number of concurrent operations based on the object size. This option does not work for small objects. The threshold for large objects to upload, download, or copy in multipart mode can be specified by using the --bigfile-threshold option. When you upload, download, or copy multiple large objects, the actual number of concurrent operations is calculated by multiplying the number of concurrent jobs by the number of concurrent operations.

Warning
  • We recommend that you adjust the number of concurrent operations to a value smaller than 100 if the resources such as network bandwidth, memory, and CPU of your ECS instance or server are limited. If resources such as the network, memory, and CPU are not fully occupied, you can increase the number of concurrent operations.
  • If you specify a large number of concurrent operations, inter-thread resource switching and snatching may degrade the upload, download, and copy performance of ossutil or lead to an EOF error. To resolve this issue, you must adjust the values of the --jobs and --parallel options based on the actual conditions. To perform stress testing, set the two options to small values at first, and slowly adjust them to the optimal values.

Common options

The following table describes the options you can add to the cp command.
Option Description
-r, --recursive Performs operations on objects in a bucket. If this option is specified, commands that support this option will perform operations on all objects in a bucket that meet the specified conditions. If this option is not specified, the commands will perform operations only on the specified object.
-f, --force Forces an operation without prompting the user for confirmation.
-u, --update Specifies that ossutil only uploads, downloads, or copies objects that do not exist in the destination bucket or objects that were modified more recently than their corresponding objects in the destination bucket.
--output-dir Specifies the folder in which the output objects are located. Output objects include report objects generated due to errors that occur when you use the cp command to copy multiple objects. The default value is the ossutil_output folder in the current folder.
--bigfile-threshold Specifies the size of a large object for which to start resumable data transfer. Unit: bytes. Valid values: non-negative integers. Default value: 100 MB.
--part-size Specifies the part size in bytes. By default, ossutil calculates the appropriate part size based on the object size. You can set this option to any positive integer if you need to optimize performance or operate under special constraints.
--checkpoint-dir Specifies the checkpoint directory. Default value: .ossutil_checkpoint. If a resumable data transfer task fails, ossutil automatically creates this directory and records the checkpoint information in the directory. If a resumable data transfer succeeds, ossutil deletes this directory. If this option is specified, ensure that you have permissions to delete the specified directory.
--range Specifies the byte range of the object to download. Bytes are numbered from 0.
  • You can specify a range. For example, 3-9 indicates a range from byte 3 to byte 9, which includes byte 3 and byte 9.
  • You can specify the field from which the download starts. For example, 3- indicates a range from byte 3 to the end of the object, which includes byte 3.
  • You can specify the field with which the download ends. For example, -9 indicates a range from byte 0 to byte 9, which includes byte 9.
--encoding-type Specifies the encoding type of the object name. If this option is specified, this value must be url. If this option is not specified, the object name is not encoded. Bucket names cannot be URL-encoded.
--include Includes objects that match a specific string such as *.jpg.
--exclude Excludes objects that match a specified string, such as *.txt.
--meta Specifies the metadata of an object in the [header:value#header:value...] format. Example: Cache-Control:no-cache#Content-Encoding:gzip. For more information, see set-meta.
--acl Configures the ACL for an object. Default value: default. Valid values:
  • default: inherited from the bucket
  • private
  • public-read
  • public-read-write
--snapshot-path If you specify the --snapshot-path option when you upload or download multiple objects, ossutil takes a snapshot of the upload or download and stores the snapshot information in a specified directory. The next time the objects are uploaded or downloaded while this option is specified, ossutil will read the snapshot information from the specified directory and perform an incremental upload or download.
Notice
  • The --snapshot-path option is used in certain scenarios to accelerate the incremental upload or download of objects. This option cannot be used to copy objects. This option can be used when the number of objects is large and no other users modify the corresponding objects in OSS between the two uploads.
  • The --snapshot-path option records the local lastModifiedTime of uploaded or downloaded objects and compares it to the lastModifiedTime of objects currently pending upload or download to determine which objects can be skipped. When using this option, ensure that the corresponding objects in OSS are not modified between the two uploads or downloads. In other scenarios where objects are updated in OSS between the two uploads or downloads, use the --update option to perform incremental upload or download on objects.
  • ossutil does not automatically delete snapshot information from the directory specified by snapshot-path. You can remove the directory if the snapshot information is no longer needed.
  • Additional overheads are required to read and write snapshot information. We recommend that you do not use this option in the following scenarios: The number of objects to upload or download is small. The network is properly connected. Other users need to perform operations on those objects. In this case, you can use the --update option to perform incremental upload or download.
  • The --update and --snapshot-path options can be used together. ossutil first uses the --snapshot-path option to determine whether to skip the upload or download of an object. If the upload or download is not skipped by --snapshot-path, ossutil then uses the --update option to determine whether to skip the upload or download of the object.
--disable-crc64 Disables CRC-64. By default, ossutil enables CRC-64 during data transmission.
--maxupspeed Specifies the maximum upload speed. Unit: KB/s. Default value: 0. 0 indicates that the maximum upload speed is unlimited.
--payer Specifies the payer of the request. If pay-by-requester is enabled, you can set this option to requester.
--partition-download Specifies the partition to download. The value of this option is in "partition number: the total number of partitions" format. A value of 1:5 indicates that ossutil downloads partition 1 out of the total five partitions. Partitions are numbered from 1. Partitioning rules for objects are determined by ossutil. This option splits an object to download into multiple partitions that can be downloaded by multiple ossutil commands. Each ossutil command downloads its own partition. You can run multiple ossutil commands on different machines at the same time.
-j, --jobs Specifies the number of concurrent jobs performed across multiple objects. Valid values: 1 to 10000. Default value: 3.
--parallel Specifies the number of concurrent operations performed on a single object. Valid values: 1 to 10000. By default, ossutil automatically sets the value of this option based on the operation type and object size.
--loglevel Specifies the log level. The default value is null, which indicates that no log files are generated. Valid values:
  • info: generates prompt logs.
  • debug: generates detailed logs that contain corresponding HTTP request and response information.
--retry-times Specifies the number of times an operation is retried if the operation fails. Valid values: 1 to 500. Default value: 10.
--version-id Specifies the version ID of an object to download or copy. You can only use this option for objects in a bucket that has versioning enabled.
--proxy-host Specifies the URL of the proxy server. HTTP, HTTPS, and SOCKS5 proxies are supported. Examples: http://120.79. **.**:3128 and socks5://120.79. **. **:1080.
--proxy-user Specifies the username of the proxy server. The default value is null.
--proxy-pwd Specifies the password of the proxy server. The default value is null.
--local-host Specifies the local IP address of ossutil. If your computer has multiple IP addresses, you can specify this option so that ossutil can access OSS through the specified IP address.
--enable-symlink-dir Specifies whether to upload the subdirectory of the symbolic link. By default, the subdirectory is not uploaded. The probe command can be used to check whether an object or a directory to which the symbolic link points is also a symbolic link.
--only-current-dir Specifies that only objects in the current directory are uploaded, downloaded, or copied. The subdirectories in the current directory are ignored.
--disable-dir-object Specifies that no OSS object is generated for the directory during object upload.
--disable-all-symlink Specifies that all objects in the subdirectory and the subdirectory to which the symbolic link points are ignored during object upload.
--tagging Specifies the object tag when you upload or copy an object in the "abc=1&bcd=2&……" format.
--disable-ignore-error Specifies that errors are not ignored during batch operations.
Note For more information about common options, see View all supported options.