You can use the cp command to download objects from OSS to your local computer.

Note For more information about the format and supported parameters of the cp command, see Overview.

Sample environment

In this topic, objects are downloaded from OSS to your local computer in Linux. You can modify the corresponding parameters based on your operating system and environment. Sample environment:

  • Operating system: Linux
  • Destination bucket: examplebucket
  • Folder specified by the destination bucket: desfolder
  • Local file: examplefile.txt (file in the root folder)
  • Local folder: localfolder (folder in the root folder)

Example for simple download

  • Download a single object

    If the name is not specified for the object you want to download, the original name is used by default. If the name of the object is specified, the file is saved to your local computer based on the specified name.

    • Save the object based on the original name
      ./ossutil cp oss://examplebucket/desfolder/examplefile.txt localfolder/
    • Save the object based on the specified name
      ./ossutil cp oss://examplebucket/desfolder/examplefile.txt localfolder/example.txt
  • Download a folder
    ./ossutil cp -r oss://examplebucket/desfolder/ localfolder/
  • Download an object from a bucket that has pay-by-requester enabled
    ./ossutil cp oss://my-bucket/test.mp4 localfolder/ --payer=requester
  • Download multiple objects without downloading the existing objects
    If you specify the --update (abbreviated as -u) option when you download multiple objects, ossutil downloads the object that has the unique name in OSS, or downloads the object that has the same name with that of the local file and whose modified time is earlier than that of the object in OSS. ossutil does not download the object that has the same name with that of the local file and whose modified time is later than that of the object in OSS. Command:
    ./ossutil cp -r oss://examplebucket/desfolder/  localfolder/  --update                           
    This option can be used to download objects that fail to download or perform incremental download.
  • Download objects only in the current folder and ignore subfolders
    ./ossutil cp oss://examplebucket/desfolder/ localfolder/ --only-current-dir -r

Range download

You can use the --range option to download part of an object within a specified range. For example, you can download the 10th to 20th characters from the examplefile.txt object as a file to your local computer.
./ossutil cp oss://examplebucket/desfolder/examplefile.txt localfolder/  --range=10-20
Succeed: Total num: 1, size: 11. OK num: 1(download 1 objects).

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 folder. The next time the objects are downloaded while this option is specified, ossutil reads the snapshot information from the specified folder and performs incremental download. For more information, see Generate snapshot information.
./ossutil cp -r oss://examplebucket/desfolder/ localfolder/ --snapshot-path=path                                

Download multiple objects that meet specified conditions

When you download multiple objects, you can use the --include and --exclude options to specify conditions to match objects. For more information, see Upload multiple objects that meet specified conditions.
  • Download all objects that are not in the JPG format
    ./ossutil cp oss://examplebucket/desfolder/ localfolder/ --exclude "*.jpg" -r
  • Download all objects that contain abc in their names and are not in the JPG or TXT format
    ./ossutil cp oss://examplebucket/desfolder/ localfolder/ --include "*abc*" --exclude "*.jpg" --exclude "*.txt" -r

Download a specified version of an object from a versioning-enabled bucket

When versioning is enabled for a bucket, data that is overwritten or deleted is saved as a previous version. You can add the --version-id option to the cp command to download a specified version of an object. Command:
./ossutil cp oss://my-bucket/test.jpg localfolder/ --version-id  CAEQARiBgID8rumR2hYiIGUyOTAyZGY2MzU5MjQ5ZjlhYzQzZjNlYTAyZDE3MDRk
Notice
  • To use the --version-id option, you must run the ls --all-versions command to query version IDs of the object.
  • 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.