Use the cp command to download files from OSS-Object Storage Service(OSS)-阿里云帮助中心

To download resources such as files, images, or videos from OSS to your local machine, use the cp command in ossutil.

Notes

To download files, you must have the oss:GetObject and oss:ListObjects permissions. For more information, see Grant custom permission policies to RAM users.
When you use the -u, --update option, the system sends at least one HEAD request for each file to compare timestamps, regardless of whether the target file exists. In scenarios where data changes infrequently, this generates many inefficient requests, which may degrade performance and incur extra request charges. Evaluate your actual business needs before using this option to avoid unnecessary resource consumption.

Command syntax

ossutil cp oss://bucket[/prefix] local-path [flags]

Parameter	Type	Description
local-path	string	Supports relative paths, absolute paths, and `-`. When set to `-`, output goes to standard output.
prefix	string	Object prefix. If the prefix ends with "/", only batch operations are supported. If it does not end with "/", the command determines whether to perform a single-object or batch download based on the command-line options.
--acl	string	Access permissions for the object. Valid values: private: private. public-read: Public read. public-read-write: public read and write. default: inherit from the bucket.
--bandwidth-limit	SizeSuffix	Limits network bandwidth to control data transfer rate. Minimum value is 1024 B/s. The default unit is B/s. You can specify a unit for the bandwidth value. Supported units include B (bytes), K (kilobytes), M (megabytes), and G (gigabytes). For example, 50 M sets the limit to 50 MB/s.
--bigfile-threshold	SizeSuffix	Threshold for enabling multipart upload, download, or copy for large files (default: 104857600).
--cache-control	string	Specifies caching behavior when the object is downloaded by a web browser.
--checkers	int	Number of concurrent checkers (default: 16).
--checkpoint-dir	string	Directory for storing resumable download checkpoint information (default: `.ossutil_checkpoint/`).
--content-disposition	string	Specifies how the object is displayed.
--content-encoding	string	Declares the encoding method of the object.
--content-type	string	Content type of the object.
--copy-props	string	Controls how metadata and tags are copied. Valid values: none: do not copy. metadata: copy metadata. default: copy both metadata and tags.
-d, --dirs	string	Download files and subdirectories in the current directory without recursively downloading all files in nested subdirectories.
--encoding-type	string	Encoding method for input object names or file names. Valid value: url.
--end-with	string	Returns objects that come before or match the specified value in alphabetical order.
--exclude	stringArray	Exclusion rules for paths or file names.
--exclude-from	stringArray	Read exclusion rules from a file.
--expires	string	Specifies the absolute expiration time for cached content.
--files-from	stringArray	Read a list of source file names from a file, ignoring empty or comment lines. Applies only to filtering scenarios.
--files-from-raw	stringArray	Read a list of source file names from a file. Applies only to filtering scenarios.
--filter	stringArray	Filtering rules for paths or file names.
--filter-from	stringArray	Read filtering rules from a file.
-f, --force	/	Force the operation without prompting for confirmation.
--include	stringArray	Inclusion rules for paths or file names.
--include-from	stringArray	Read inclusion rules from a file.
-j, --job	int	Number of concurrent tasks (default: 3). Note This parameter takes effect only if you also specify any of the following: `-f`, `--update`, `--size-only`, or `--ignore-existing`.
--list-objects	/	Use the ListObjects API to list objects.
--max-size	SizeSuffix	Maximum file size to transfer. Default unit is bytes. You can append a suffix: B\|K\|M\|G\|T\|P. Note: 1K (KiB) = 1024B.
--metadata	strings	User-defined metadata for the object, in key=value format.
--metadata-directive	string	Specifies how to set metadata for the destination object. Valid values: COPY REPLACE
--metadata-exclude	stringArray	Exclusion rules for object metadata.
--metadata-filter	stringArray	Filtering rules for object metadata.
--metadata-filter-from	stringArray	Read object metadata filtering rules from a file.
--metadata-include	stringArray	Inclusion rules for object metadata.
--min-age	Duration	Download only files modified before the specified time interval. Default unit is seconds. You can use suffixes like h (hours). For example, 1h means 1 hour. Note `--min-age 1h` downloads only files modified one hour ago or earlier.
--max-age	Duration	Download only files modified within the specified time interval. Default unit is seconds. You can use suffixes like h (hours). For example, 1h means 1 hour. Note `--max-age 1h` downloads only files modified within the last hour.
--min-mtime	Time	Download only files modified after the specified time. Time format: UTC, for example, 2006-01-02T15:04:05. Note `--min-mtime "2006-01-02T15:04:05"` downloads only files modified after January 2, 2006 at 15:04:05 UTC.
--max-mtime	Time	Download only files modified before the specified time. Time format: UTC, for example, 2006-01-02T15:04:05.
--min-size	SizeSuffix	Minimum file size to transfer. Default unit is bytes. You can append a suffix: B\|K\|M\|G\|T\|P. Note: 1K (KiB) = 1024B.
--no-progress	/	Do not display the progress bar.
--page-size	int	Maximum number of objects listed per page during batch download (default: 1000). Valid range: 1–1000.
--parallel	int	Number of concurrent tasks for internal operations on a single file.
--part-size	SizeSuffix	Part size for multipart operations. By default, ossutil calculates an appropriate part size based on file size. Valid range: 100 KiB–5 GiB.
-r, --recursive	/	Perform operations recursively. When this option is specified, the command operates on all matching objects in the bucket. Otherwise, it operates only on the object specified by the path.
--request-payer	string	Payment method for the request. Set this to requester if the bucket uses pay-by-requester mode.
--size-only	/	Download only source files whose sizes differ from those of the destination files.
--start-after	string	Returns objects that come after the specified value in alphabetical order, excluding the value itself.
--storage-class	string	Storage class of the object. Valid values: Standard: Standard storage. IA: Infrequent Access storage. Archive: Archive Storage. ColdArchive: Cold Archive storage. DeepColdArchive: Deep Cold Archive storage.
--tagging	strings	Tags for the object, in key=value format.
--tagging-directive	string	Specifies how to set tags for the destination object. Valid values: COPY REPLACE
-u, --update	/	Skip files that already exist at the destination and have a newer modification time than the source files. Note If a file already exists at the destination but has an older modification time than the source file, it will be updated.
--ignore-existing	/	Skip files that already exist at the destination.
--version-id	string	Version ID of the object.
--write-buffer-size	SizeSuffix	Size of the memory buffer used for writes. Automatically aligned to 4 KB boundaries. Supports suffixes B / K / M (default: 128 KiB). Valid range: 0–32 MiB.

Note

Starting from ossutil 2.3.0, the options --job, --parallel, --bigfile-threshold, --part-size, and --write-buffer-size can be configured in a configuration file. Add them under the corresponding profile section in key=value format (for example, job=10), or use ossutil config set to write them. Command-line options take precedence over configuration file settings.

Note

For supported global command-line options, see Global command-line options.

Naming rules for destination files are as follows:

For single-file downloads, if the destination is a directory, the file is created in that directory using the source file's relative path.
For single-file downloads, if the destination is a file or does not exist, the specified destination file name is used.
For batch downloads, subdirectories are created level by level under the destination root directory according to the source files' relative paths, and then the files are created.

Note

The relative path of a source file is derived by removing all characters up to and including the last '/' in the prefix.

For example, in cp oss://bucket/root/dir/ ..., the object root/dir/subdir/test.txt has the relative path subdir/test.txt.

Examples

Download a single file

If you do not specify a file name during download, the original file name is used locally. If you specify a file name, the file is saved locally with that name.

Save using the original file name

ossutil cp oss://examplebucket/examplefile.txt D:/localpath

Save using a specified file name

ossutil cp oss://examplebucket/examplefile.txt D:/localpath/example.txt

Download multiple files

Download files of a specific type

To download multiple files that share a naming pattern—such as a common prefix or suffix—use the --include and --exclude options to select matching files.

Download all files except those with the JPG format:
```
ossutil cp oss://examplebucket/destfolder/ D:/localpath/ --exclude "*.jpg" -r
```

Downloads folder

ossutil cp -r oss://examplebucket/destfolder/ D:/localpath/

Download all files from the bucket root

ossutil cp -r oss://examplebucket  D:/localpath/

Throttle download speed

Download examplefile.txt to the current directory and limit the download speed to 20 MB/s.

ossutil cp oss://examplebucket/examplefile.txt . --bandwidth-limit 20971520