All Products
Search

This Product

    Object Storage Service:cp (Download objects)

    Document Center

    Object Storage Service:cp (Download objects)

    Last Updated:Mar 20, 2026

    Use the cp command to download objects from Object Storage Service (OSS) to your local machine. Supports single-object downloads, batch recursive downloads, range downloads, speed limiting, filtered downloads, and versioned-object downloads.

    Usage notes

    Starting from ossutil 1.6.16, ossutil works as the binary name on all operating systems. Earlier versions require an OS-specific binary name. For details, see ossutil command reference.

    Permissions

    By default, an Alibaba Cloud account has full permissions on its resources. A Resource Access Management (RAM) user or RAM role has no permissions by default. Grant permissions using a RAM policy or a bucket policy.

    API actionDescription
    oss:GetObjectRequired to download an object.
    oss:GetObjectVersionOptional. Required to download a specific version using --version-id.
    kms:GenerateDataKeyOptional. Required if the object is server-side encrypted with KMS.
    kms:DecryptOptional. Required if the object is server-side encrypted with KMS.
    oss:ListObjectsOptional. Required for batch downloads (recursive operations).

    Syntax

    ossutil cp <cloud_url> <file_url> [options]

    cloud_url is the OSS source path (oss://bucket[/prefix], for example oss://examplebucket/examplefile.txt).

    file_url is the local destination path. To save to a directory, end the path with a separator (/ on Linux, \ on Windows). For example: /localfolder/ or D:\localfolder\.

    Options

    Basic download options

    OptionDescription
    -r, --recursiveDownloads all objects under the specified prefix. Without this option, only the single specified object is downloaded.
    -f, --forceForces the operation without prompting for confirmation.
    -u, --updateDownloads an object only if the local file doesn't exist or the OSS object has a later last-modified time.
    --only-current-dirDownloads only objects in the current directory, ignoring subdirectories.
    --encoding-typeEncoding type for object names. Set to url to URL-encode names.
    --disable-crc64Disables CRC-64 verification. CRC-64 is enabled by default for all transfers.
    --payerPayment method for the request. Set to requester to enable requester-pays.

    Filter options

    OptionDescription
    --includeDownloads only objects matching the specified pattern. For details, see include and exclude options.
    --excludeSkips objects matching the specified pattern. For details, see include and exclude options.
    --start-timeA UNIX timestamp. Objects with a last-modified time earlier than this value are skipped. Requires ossutil 1.7.18 or later.
    --end-timeA UNIX timestamp. Objects with a last-modified time later than this value are skipped. If both --start-time and --end-time are set, only objects modified within that range are downloaded. Requires ossutil 1.7.18 or later.

    Performance options

    OptionDescription
    -j, --jobsNumber of concurrent tasks for multi-object operations. Default: 3. Value range: 1–10,000.
    --parallelNumber of concurrent tasks for single-object operations. Value range: 1–10,000. If not set, ossutil determines the value based on operation type and object size.
    --maxdownspeedMaximum download speed in KB/s. Default: 0 (no limit).
    --snapshot-pathDirectory to store snapshot information for incremental downloads. On subsequent runs with this option, ossutil reads the snapshot to skip already-downloaded objects.

    Advanced options

    OptionDescription
    --rangeDownloads a specific byte range of the object. Byte numbering is zero-based. Formats: 3-9 (bytes 3 to 9, inclusive), 3- (byte 3 to end), -9 (bytes 0 to 9).
    --bigfile-thresholdSize threshold in bytes for resumable download. Default: 100 MB. Value range: 0–9,223,372,036,854,775,807.
    --part-sizePart size in bytes for resumable downloads. By default, ossutil calculates an appropriate size. Value range: 1–9,223,372,036,854,775,807.
    --checkpoint-dirDirectory to store checkpoint files for resumable downloads. On failure, ossutil creates a .ossutil_checkpoint directory here. The directory is deleted after a successful download. Make sure the directory can be deleted.
    --disable-ignore-errorCauses the command to stop on the first error in batch operations instead of skipping it.
    --version-idDownloads a specific version of an object. For use with versioning-enabled buckets only. To enable versioning, see bucket-versioning (Versioning).
    --partition-downloadDownloads a partition of the object. Format: <partition number>:<total partitions>. For example, 1:5 downloads partition 1 of 5. Partition numbers are 1-based. Use multiple ossutil commands in parallel, each with a different partition number, to split and download a large object concurrently.
    --metaSets metadata on the downloaded object. Format: header:value#header:value. Example: Cache-Control:no-cache#Content-Encoding:gzip. For details, see set-meta (Manage object metadata).
    --aclAccess control list (ACL) for the object. Valid values: default (inherits the bucket ACL), private, public-read (all users including anonymous users have read access — this can lead to data leaks and increased fees, use with caution), public-read-write (anyone including anonymous users can read and write — this can lead to data leaks, increased fees, and potential legal liabilities, avoid unless required for specific use cases).

    For additional common options, see Common options.

    Performance tuning

    For batch transfers of large objects, actual concurrency = -j (jobs) x --parallel. Tune both options based on your machine's network, memory, and CPU resources.

    • If resources are constrained, keep concurrency below 100.

    • Setting concurrency too high causes thread-switching overhead and can produce EOF errors. Start with a low value and increase gradually to find the optimal setting.

    Examples

    All examples use a Linux system. Adjust paths and separators for your OS.

    Assumptions:

    • Bucket: examplebucket

    • OSS directory: destfolder/

    • Local directory: localfolder/

    Download a single object

    Download an object and keep its original name:

    ossutil cp oss://examplebucket/destfolder/examplefile.txt localfolder/

    Download an object and rename it to example.txt:

    ossutil cp oss://examplebucket/destfolder/examplefile.txt localfolder/example.txt

    Batch download

    Before running a large batch download, use the ls command to confirm which objects will be affected.

    Use -r to download destfolder and all its subdirectories:

    ossutil cp -r oss://examplebucket/destfolder/ localfolder/

    Use --only-current-dir to download only the objects in destfolder, skipping any subdirectories:

    ossutil cp -r oss://examplebucket/destfolder/ localfolder/ --only-current-dir

    Use -u to skip objects that already exist locally with the same last-modified time (incremental download):

    ossutil cp -r -u oss://examplebucket/destfolder/ localfolder/

    Download filtered objects

    Download all objects in destfolder except JPG files:

    ossutil cp -r oss://examplebucket/destfolder/ localfolder/ --exclude "*.jpg"

    Download objects whose names contain abc but are not JPG or TXT files:

    ossutil cp -r oss://examplebucket/destfolder/ localfolder/ --include "*abc*" --exclude "*.jpg" --exclude "*.txt"

    Limit download speed

    Limit download speed to 1 MB/s (1,024 KB/s):

    ossutil cp -r oss://examplebucket/destfolder/ localfolder/ --maxdownspeed 1024

    Range download

    Download bytes 10 to 20 of an object:

    ossutil cp oss://examplebucket/destfolder/examplefile.txt localfolder/ --range 10-20

    Download objects within a time range

    Download only objects in destfolder last modified between 10:09:18 and 12:55:58 on October 31, 2023 (UTC+8):

    ossutil cp -r oss://examplebucket/destfolder/ localfolder/ --start-time 1698718158 --end-time 1698728158

    Download a specific version

    First, get all version IDs for the object:

    ossutil ls --all-versions oss://examplebucket/test.jpg

    Then download the specific version:

    ossutil cp oss://examplebucket/test.jpg localfolder/ --version-id CAEQARiBgID8rumR2hYiIGUyOTAyZGY2MzU5MjQ5ZjlhYzQzZjNlYTAyZDE3MDRk
    --version-id requires a versioning-enabled bucket. To enable versioning, see bucket-versioning (Versioning).

    Download objects and generate snapshot information

    Use --snapshot-path to record which objects were downloaded. Subsequent downloads with the same option skip already-downloaded objects:

    ossutil cp -r oss://examplebucket/destfolder/ localfolder/ --snapshot-path /path/to/snapshot/dir/

    For details on how snapshot information works, see Upload objects and generate snapshots.

    Cross-account or cross-region download

    Use the -e, -i, and -k options to download from a bucket owned by another account in the China (Shanghai) region:

    ossutil cp oss://examplebucket/exampleobject.txt localfolder/ -e oss-cn-shanghai.aliyuncs.com -i <yourAccessKeyID> -k <yourAccessKeySecret>
    Specify the endpoint for the region where the bucket is located. For a full list of endpoints, see Regions and endpoints.