Docs

Torch Object Storage

Common examples

Downloading objects

This topic provides examples of how to download objects with common tosutil commands on macOS.

Example bucket and example objects

The example bucket is named bucketname and contains the following objects:

tos://bucketname/file1.txt​
tos://bucketname/file2.txt​
tos://bucketname/pic1.png​
tos://bucketname/pic2.png​
tos://bucketname/pic3.jpg​
tos://bucketname/pic4.jpg​
tos://bucketname/folder1/​
tos://bucketname/folder1/file7.txt​
tos://bucketname/folder2/​
tos://bucketname/folder2/file8.txt​
tos://bucketname/folder2/folder3/​
tos://bucketname/folder2/folder3/file9.txt​

Common examples

The following commands illustrate various download scenarios based on the objects of the example bucket.

Download an object from a bucket to a local folder

Download the file1.txt object from the bucketname bucket to the local folder1 folder

./tosutil cp tos://bucketname/file1.txt /folder1

After the download is complete, the following file will be generated on your local device:

└── folder1​
    └── file1.txt​

Download an object from the bucket to a local folder and rename it

Download the file1.txt object from the bucketname bucket to the local folder1 folder and rename it to file1_renamed.txt

tip

If file1_renamed.txt does not exist in the local folder1 folder, the file will be downloaded and saved directly as file1_renamed.txt. If file1_renamed.txt already exists, the download will overwrite it with the contents of file1.txt.

./tosutil cp tos://bucketname/file1.txt /folder1/file1_renamed.txt

After the download is complete, the local file will be:

└── folder1​
    └── file1_renamed.txt​

Download a folder (including the folder itself) from a bucket

Download all objects and subfolders in the folder2 folder (including the folder itself) from the bucketname bucket to the local folder1 folder:

./tosutil cp tos://bucketname/folder2/ /folder1/ -r

After the download is complete, the following files and folders will be generated on your local device:

└── folder1​
    └── folder2​
        ├── file8.txt​
        └── folder3​
            └── file9.txt​

Download a folder (excluding the folder itself) from a bucket

Download all objects and subfolders in the folder2 folder (excluding the folder itself) from the bucketname bucket to the local folder2_renamed folder:

./tosutil cp tos://bucketname/folder2 /folder2_renamed -r -flat

After the download is complete, the following files and folders will be generated on your local device:

└── folder2_renamed​
    ├── file8.txt​
    └── folder3​
        └── file9.txt​

Download all objects in a bucket

Download all objects from the bucketname bucket to the folder0 folder

./tosutil cp tos://bucketname /folder0 -r

After the download is complete, the following files and folders will be generated on your local device:

└── folder0​
    ├── file1.txt​
    ├── file2.txt​
    ├── pic1.png​
    ├── pic2.png​
    ├── pic3.jpg​
    ├── pic4.jpg​
    ├── folder1​
        └── file7.txt​
    └── folder2​
        ├── file8.txt​
        └── folder3​
            └── file9.txt​

Download objects that meet the specified conditions from a bucket

Download all .txt and pi?1.png objects from the bucketname bucket to the folder0 folder

./tosutil cp tos://bucketname /folder0 -r -include=*.txt#*pi?1.png

After the download is complete, the following files and folders will be generated on your local device:

└── folder0​
    ├── file1.txt​
    ├── file2.txt​
    ├── pic1.png​
    ├── folder1​
        └── file7.txt​
    └── folder2​
        ├── file8.txt​
        └── folder3​
            └── file9.txt​

Last updated: 2025.12.17 18:33:44