This topic describes how to run the cp command to download objects from Object Storage Service (OSS) to your local computer.
./ossutil64 cp cloud_url file_url [-r, --recursive] [-f --force] [-u --update] [--maxdownspeed <value>] [--disable-ignore-error] [--only-current-dir] [--bigfile-threshold <value>] [--part-size <value>] [--checkpoint-dir <value>] [--range <value>] [--encoding-type <value>] [--include <value>] [--exclude <value>] [--meta <value>] [--acl <value>] [--snapshot-path <value>] [--disable-crc64] [--payer <value>] [--partition-download <value>] [-j, --job <value>] [--parallel <value>] [--version-id <value>]
The following table describes the parameters that you can configure when you run this command to download objects from OSS.
|cloud_url||Specifies the path of the object that you want to download from OSS. Format:
|file_url||Specifies the local path to which you want to download the object from OSS. Examples:
The local path in Linux is
|-r, --recursive||Specifies recursive operations. If this option is specified, commands that support this option are run to perform operations on all objects in a bucket that meet the specified conditions. If this option is not specified, commands that support this option are run to perform operations only on the specified object.|
|-f --force||Forces an operation without prompting the user for confirmation.|
|-u, --update||Specifies that ossutil downloads an object from OSS only when the destination file does not exist in the local computer or when the last modified time of the source object is later than that of the destination file.|
|--maxdownspeed||Specifies the maximum download speed. Unit: KB/s. The default value is 0, which indicates that the download speed is unlimited.|
|--disable-ignore-error||Specifies that errors are not ignored during batch operations.|
|--only-current-dir||Specifies that only objects in the current directory are downloaded. Subdirectories in the current directory and objects in these subdirectories are not downloaded.|
|--bigfile-threshold||Specifies the maximum size of objects that can be downloaded by using resumable download.
Default value: 104857600 (100 MB).
Valid values: 0 to 9223372036854775807.
|--part-size||Specifies the part size. Unit: bytes. By default, ossutil determines the part size
based on the object size.
Valid values: 1 to 9223372036854775807.
|--checkpoint-dir||Specifies the directory in which the log information of resumable upload or download
tasks is stored. Default value:
|--range||Specifies that a specific range of the object content is downloaded and stored as
a new object in the destination local path. The minimum start value of the range is
0, which indicates the byte 0 of the content of the object. You can set this parameter
in one of the following formats:
|--encoding-type||Specifies the method used to encode the names of objects. Valid values: url. If you do not specify this parameter, the names of objects are not encoded.|
|--include||Specifies that the command applies to all objects that meet the specified conditions.|
|--exclude||Specifies that the command applies to all objects that do not meet the specified conditions.|
|--meta||Specifies that the metadata of an object is in the
|--acl||Specifies the access control list (ACL) of the object to download. Default value:
private. Valid values:
|--snapshot-path||Specifies the directory in which the snapshots of downloaded objects are stored. In the next download task, ossutil reads the snapshots in this directory to download only incremental objects.|
|--disable-crc64||Specifies that CRC-64 is disabled. By default, CRC-64 is enabled when you use ossutil to transfer data.|
|--payer||The payer of the traffic and request fees charged when the command is run. If you want the requester who accesses the resources in the specified path to pay for the traffic and request fees charged during downloads, set this parameter to requester.|
|--partition-download||Specifies the partition in which the object that you want to download is stored. The
value of this option is in the
|-j, --job||Specifies the number of objects to download concurrently. Valid values: 1 to 10000. Default value: 3.|
|--parallel||Specifies the number of concurrent tasks run to download a single object. Valid values: 1 to 10000. By default, if you do not set this parameter, ossutil sets the value of this parameter based on the operation type and the size of the object to download.|
|--version-id||Specifies the version ID of the object that you want to download. You can use this option for objects only in a bucket that has versioning enabled.|
When the default configuration of the number of concurrent tasks based on the -j, --jobs and --parallel options cannot meet your performance requirements, you can configure these two parameters based on your requirements. By default, ossutil calculates the number of concurrent operations based on the size of the object to download. When you download multiple large objects, the actual number of concurrent tasks is calculated by multiplying the value of -j, --jobs by the value of --parallel.
- We recommend that you adjust the number of concurrent tasks to a value smaller than 100 if the resources such as network bandwidth, memory, and CPU of your Elastic Compute Service (ECS) instance or server are limited. If the maximum resources such as the network bandwidth, memory, and CPU are not reached, you can increase the number of concurrent operations.
- If the number of concurrent tasks is too large, the download performance of ossutil may decrease, or an end-of-file (EOF) error may occur because thread resources are switched and threads compete for resources. To resolve this issue, you must adjust the values of the -j, --jobs and --parallel options based on the actual conditions of machines. When you perform stress testing, set a small value for the two options before you incrementally increase them to the optimal values.
In this topic, objects are downloaded from OSS to your local directory in Linux. You can modify the parameters in the following examples based on your operating system and environment. Sample environment:
- Operating system: Linux
- Destination bucket: examplebucket
- Directory of the destination bucket: desfolder
- Local file: examplefile.txt. This file is stored in the root directory of the local computer.
- Local directory: localfolder. This directory is stored in the root directory of the local computer.
Download a single object
If you do not specify a name for the destination object, the name of the source object is used by default. If you specify a name for the destination object, the specified name is used in the local computer.
- You can run the following command to save the destination object with the name of
the source object:
./ossutil64 cp oss://examplebucket/destfolder/examplefile.txt localfolder/
- You can run the following command to save the destination object with a specified
./ossutil64 cp oss://examplebucket/destfolder/examplefile.txt localfolder/example.txt
Download multiple objects
You cannot use ossutil to download multiple objects at the same time by specifying multiple object names. You can download multiple objects at the same time by using the following methods:
- Download a type of objects
If you want to download multiple objects whose names contain the same prefix or suffix, you can use the --include and --exclude options to download objects that meet specific conditions.
- You can run the following command to download all objects that are not in the JPG format:
./ossutil64 cp oss://examplebucket/destfolder/ localfolder/ --exclude "*.jpg" -r
- You can run the following command to download all objects that contain abc in their names and are not in the JPG or TXT format:
./ossutil64 cp oss://examplebucket/destfolder/ localfolder/ --include "*abc*" --exclude "*.jpg" --exclude "*.txt" -r
- You can run the following command to download all objects that are not in the JPG format:
- Download a directory and its subdirectories
You can run the following command to download all objects in a directory, including subdirectories in the directory:
./ossutil64 cp -r oss://examplebucket/destfolder/ localfolder/
When a batch download task fails or when you want to implement incremental download, you can use the --update option that can be shortened to -u to skip objects that have been downloaded. If an object does not have the same name as local files, or the object is last modified later than the local file that has the same name, ossutil downloads the object. Otherwise, ossutil skips the object. Example:
./ossutil64 cp -r oss://examplebucket/destfolder/ localfolder/ --update
- Download a directory (excluding its subdirectories)
If you want to download only the current directory and ignore its subdirectories, use the --only-current-dir option. Example:
./ossutil64 cp oss://examplebucket/destfolder/ localfolder/ --only-current-dir -r
Limit download speed
- You can run the following command to download objects from OSS and set the value of
the --maxdownspeed parameter to 1 MB/s:
./ossutil64 cp oss://examplebucket/destfolder/examplefile.txt localfolder/ --maxdownspeed 1024
- You can run the following command to download directories from OSS and set the value
of the --maxdownspeed parameter to 1 MB/s:
./ossutil64 cp -r oss://examplebucket/destfolder/ localfolder/ --maxdownspeed 1024
Download a range of an object
./ossutil64 cp oss://examplebucket/destfolder/examplefile.txt localfolder/ --range=10-20 Succeed: Total num: 1, size: 11. OK num: 1(download 1 objects).
Download a directory and generate snapshot information
./ossutil64 cp -r oss://examplebucket/destfolder/ localfolder/ --snapshot-path=path
Download a specified version of an object from a versioned bucket
./ossutil64 cp oss://my-bucket/test.jpg localfolder/ --version-id CAEQARiBgID8rumR2hYiIGUyOTAyZGY2MzU5MjQ5ZjlhYzQzZjNlYTAyZDE3MDRk
If you use ossutil to switch to a bucket that is located in a different region, you can use the -e option to specify the endpoint of the region in which the specified bucket resides. If you use ossutil to switch to a bucket that belongs to another Alibaba Cloud account, you can use the -i option to specify the AccessKey ID of the specified account, and use the -k option to specify the AccessKey secret of the specified account.
./ossutil64 cp oss://examplebucket/exampleobject.txt localfolder/ -e oss-cn-shanghai.aliyuncs.com -i LTAI4Fw2NbDUCV8zYUzA**** -k 67DLVBkH7EamOjy2W5RVAHUY9H****
For more information about other common options that you can use for the cp command, see Common options.