ls (List buckets, objects, or parts) - Object Storage Service

The ls command lists information about buckets, objects, and parts in your account. Use this command to query and manage your Object Storage Service (OSS) resources, for example, to find and delete large objects to manage storage usage.

Usage notes

Starting from ossutil 1.6.16, you can use ossutil as the binary name in your commands regardless of your OS. For versions earlier than 1.6.16, you must use the binary name specific to your OS. For more information, see ossutil command reference.

Permissions

Alibaba Cloud accounts have full permissions by default. In contrast, RAM users and RAM roles have no default permissions. The account owner or an administrator must grant them permissions by using a RAM policy or bucket policy.

API Action	Description
`oss:ListBuckets`	Required to run the `ls` command to list buckets in an account.
`oss:ListObjects`	Required to run the `ls` command to list objects in a specified bucket.
`oss:ListObjectVersions`	Optional. Required to list all versions of an object when using the `--all-versions` option.
`oss:ListMultipartUploads`	Optional. Required to list incomplete or aborted multipart uploads.
`oss:ListParts`	Optional. Required to list parts.

Command syntax

ossutil ls cloud_url [options]

Parameters

Parameter	Description
cloud_url	Specifies the resource to operate on. The format is `oss://[bucket_name[/prefix]]`. If omitted, all buckets that you have permission to access in the current account are listed. If you specify `oss://bucket_name`, all objects in the bucket are recursively listed. If you specify `oss://bucket_name/prefix`, all objects in the bucket that match the specified prefix are recursively listed.
-s, --short-format	Displays the output in a simplified format. The result includes only resource names.
-d, --directory	Performs a non-recursive listing. Lists only the objects and first-level subdirectories (common prefixes that end with `/`) in the current path.
-m, --multipart	Lists all incomplete or aborted multipart upload tasks in the specified bucket. Note: Incomplete parts occupy storage space and incur fees. Check for and clear them regularly.
-a, --all-type	Lists all types of resources, including objects and incomplete parts.
--limited-num	Specifies the maximum number of results to return in a single request. This option can be used for pagination. To avoid request timeouts when listing many objects, use this option with the `--marker` option for pagination.
--marker	Starts the listing from the specified marker. If a bucket contains many objects, use this option with the `--limited-num` option for pagination.
--upload-id-marker	Resumes listing incomplete multipart uploads from the specified UploadID.
--payer	Specifies that the requester pays for the access. If you set this option to `requester`, the requester pays for fees that are generated, such as traffic fees and request fees.
--include	Lists objects that match the specified wildcard pattern. For more information, see --include and --exclude options.
--exclude	Excludes objects that match the specified wildcard pattern from the listing. For more information, see --include and --exclude options.
--all-versions	Lists all historical versions of an object. This option is valid only for versioning-enabled buckets.
--version-id-marker	Resumes listing the historical versions of an object from the specified version ID. This option is valid only for versioning-enabled buckets.

For more information about other common options for this command, see Common options.

Output results

The ETag value in the returned object list is used to verify the integrity of the object content.

For an object created using PutObject, its ETag is the MD5 hash of its content.
For an object created using other methods, such as a multipart upload, its ETag is a unique value, not the MD5 hash of its content.

Examples

List all buckets

Run the ls command without any parameters to list all accessible buckets in your account.

ossutil ls

Or:

ossutil ls oss://

Sample output:

2016-10-21 16:18:37 +0800 CST       oss-ap-southeast-1         Archive    oss://examplebucketA
2016-12-01 15:06:21 +0800 CST       oss-ap-southeast-1        Standard    oss://examplebucketB
2016-07-20 10:36:24 +0800 CST       oss-ap-southeast-1              IA    oss://examplebucketC
2016-10-21 17:31:27 +0800 CST       oss-ap-southeast-1         Archive    oss://examplebucketD
Bucket Number is:4
0.252174(s) elapsed

List buckets in simple mode

ossutil ls -s

Sample output:

oss://examplebucketA
oss://examplebucketB
oss://examplebucketC
oss://examplebucketD
Bucket Number is:4
0.235104(s) elapsed

List buckets by page

If you have many buckets, use the --limited-num and --marker options to list them by page.

List buckets whose names are alphabetically after the marker examplebucketA.

ossutil ls  --limited-num=2 -s --marker examplebucketA

Sample output:

2016-12-01 15:06:21 +0800 CST       oss-ap-southeast-1        Standard    oss://examplebucketB
2016-07-20 10:36:24 +0800 CST       oss-ap-southeast-1              IA    oss://examplebucketC
Bucket Number is:2
0.132174(s) elapsed

List all objects in a specified bucket

List all objects in the examplebucket bucket.

ossutil ls oss://examplebucket

Sample output:

LastModifiedTime                    Size(B)  StorageClass   ETag                                    ObjectName
2020-12-01 15:06:37 +0800 CST           114      Standard   61DE142E5AFF9A6748707D4A77BFBCFB        oss://examplebucket/example.txt
2020-12-01 15:06:42 +0800 CST        363812      Standard   E7581E5D2EBC56ECCB6FB6050B4C6545        oss://examplebucket/examplefolder/photo.jpg
2020-12-01 15:06:45 +0800 CST      57374182      Standard   BE97B7AD7A2C1277B11221E5C9537544        oss://examplebucket/video.mp4
Object Number is:3
0.007379(s) elapsed

The ETag value is used to identify the content of an object. For an object created using a PutObject request, the ETag value is the MD5 hash of the object content. For an object created using other methods, the ETag value is a unique value that is generated based on specific rules and is not the MD5 hash of the object content.

List objects in a specified directory (prefix)

List objects that have the example prefix in the examplebucket bucket.

ossutil ls oss://examplebucket/example

Sample output:

LastModifiedTime                    Size(B)  StorageClass   ETag                                     ObjectName
2020-12-01 15:06:37 +0800 CST           114      Standard   61DE142E5AFF9A6748707D4A77BFBCFB        oss://examplebucket/example.txt
2020-12-01 15:06:42 +0800 CST        363812      Standard   E7581E5D2EBC56ECCB6FB6050B4C6545        oss://examplebucket/examplefolder/photo.jpg
Object Number is:2
0.007379(s) elapsed

List objects with a specified suffix

Use the --include option to list all .mp4 files in the examplebucket bucket.

ossutil ls oss://examplebucket --include *.mp4

Sample output:

LastModifiedTime                    Size(B)  StorageClass   ETag                                     ObjectName
2020-12-01 15:06:45 +0800 CST      57374182      Standard   BE97B7AD7A2C1277B11221E5C9537544        oss://examplebucket/video.mp4
Object Number is:1
0.007379(s) elapsed

Non-recursively list objects and first-level subdirectories

Use the -d option to list only the objects and first-level subdirectories in the root directory of the examplebucket bucket. The contents of the subdirectories are not recursively listed.

ossutil ls oss://examplebucket -d

Sample output:

oss://examplebucket/example.txt
oss://examplebucket/examplefolder/
oss://examplebucket/video.mp4
Object and Directory Number is: 3
0.278(s) elapsed

List all versions of all objects

For a versioning-enabled bucket, use the --all-versions option to list all object versions.

ossutil ls oss://examplebucket --all-versions

Sample output:

LastModifiedTime                   Size(B)  StorageClass   ETag                                   VERSIONID                                                           IS-LATEST   DELETE-MARKER   ObjectName
2020-12-01 15:06:37 +0800 CST         114      Standard   61DE142E5AFF9A6748707D4A77BFBCFB      CAEQARiBgICUsOuR2hYiIDI3NWVjNmEyYmM0NTRkZWNiMTkxY2VjMDMwZjFlMDA3    true        false           oss://examplebucket/example.txt
2020-06-11 11:03:37 +0800 CST      363812      Standard   E7581E5D2EBC56ECCB6FB6050B4C6545      CAEQARiBgIDZtvuR2hYiIDNhYjRkN2M5NTA5OTRlN2Q4YTYzODQwMzQ4NDYwZDdm    true        false           oss://examplebucket/examplefolder/photo.jpg
2021-01-26 13:27:08 +0800 CST           0                                                       CAEQLxiBgIDd7NH0uRciIDA3Yzg0MTZjOWNlYzQ4ODZhMzVkZWE0MmE2NzBlYTYx    true        true            oss://examplebucket/image.png
2020-12-01 15:06:45 +0800 CST    57374182      Standard   BE97B7AD7A2C1277B11221E5C9537544      CAEQLBiBgMDZiprwthciIDY2NGM0NTNmZDE3ODRmZmVhZGM4YTUwZGQyNGU3ZjQ3    true        false           oss://examplebucket/video.mp4
2016-06-11 10:53:46 +0800 CST      118076      Standard   FFDB300F053AAF06F4C4C58A4869C427      CAEQARiBgID8rumR2hYiIGUyOTAyZGY2MzU5MjQ5ZjlhYzQzZjNlYTAyZDE3MDRk    false       false           oss://examplebucket/example.txt
2016-06-11 11:02:05 +0800 CST      345374      Standard   078A9852BCF81DC4811E6EDCBFD121BE      CAEQARiBgICNz_iR2hYiIGJjZTBjNDQxYWRhNTQ2ZTNiNmMzYzQ1YzMzMDA5ZjUw    false       false           oss://examplebucket/examplefolder/photo.jpg
Object Number is: 6

0.692000(s) elapsed

List all versions of a specified object

For a versioning-enabled bucket, use the --all-versions option to list all versions of example.txt.

ossutil ls oss://examplebucket/example.txt --all-versions

Sample output:

LastModifiedTime                   Size(B)  StorageClass  ETag                                   VERSIONID                                                           IS-LATEST   DELETE-MARKER  ObjectName
2020-12-01 15:06:37 +0800 CST         114      Standard   61DE142E5AFF9A6748707D4A77BFBCFB      CAEQARiBgICUsOuR2hYiIDI3NWVjNmEyYmM0NTRkZWNiMTkxY2VjMDMwZjFlMDA3    true        false           oss://examplebucket/example.txt
2016-06-11 10:53:46 +0800 CST         114      Standard   61DE142E5AFF9A6748707D4A77BFBCFB      CAEQARiBgID8rumR2hYiIGUyOTAyZGY2MzU5MjQ5ZjlhYzQzZjNlYTAyZDE3MDRk    false       false           oss://examplebucket/example.txt
Object Number is: 2
0.361(s) elapsed

List all parts

Use the -m option to list all incomplete parts in examplebucket that result from interrupted or failed uploads. These parts consume storage space and incur charges. Delete these parts regularly to avoid unnecessary costs.

ossutil ls oss://examplebucket -m

Sample output:

InitiatedTime                     UploadID                           ObjectName
2017-01-13 03:45:26 +0000 CST     15754AF7980C4DFB8193F190837520BB    oss://examplebucket/test.mp4
2017-01-20 11:16:21 +0800 CST     A20157A7B2FEC4670626DAE0F4C0073C    oss://examplebucket/object.exe
UploadId Number is: 2
0.191(s) elapsed

List all objects and parts

Use the -m option to list all objects and parts in examplebucket.

ossutil ls oss://examplebucket -a

Sample output:

LastModifiedTime                    Size(B)  StorageClass   ETag                                     ObjectName
2020-12-01 15:06:37 +0800 CST           114      Standard   61DE142E5AFF9A6748707D4A77BFBCFB        oss://examplebucket/example.txt
2020-12-01 15:06:42 +0800 CST        363812      Standard   E7581E5D2EBC56ECCB6FB6050B4C6545        oss://examplebucket/examplefolder/photo.jpg
2020-12-01 15:06:45 +0800 CST      57374182      Standard   BE97B7AD7A2C1277B11221E5C9537544        oss://examplebucket/video.mp4
Object Number is:3
InitiatedTime                     UploadID                           ObjectName
2017-01-13 03:45:26 +0000 CST     15754AF7980C4DFB8193F190837520BB    oss://examplebucket/test.mp4
2017-01-13 03:45:13 +0000 CST     2A1F9B4A95E341BD9285CC42BB950EE0    oss://examplebucket/test.mp4
2017-01-13 03:45:01 +0000 CST     3998971ACAF94AD9AC48EAC1988BE863    oss://examplebucket/test.mp4
2017-01-20 11:16:21 +0800 CST     A20157A7B2FEC4670626DAE0F4C0073C    oss://examplebucket/object.exe
UploadId Number is:4
0.791289(s) elapsed

List resources authorized by another account

List all objects in a test bucket that belongs to another Alibaba Cloud account in the Singapore region.

ossutil ls oss://test -e oss-ap-southeast-1.aliyuncs.com -i yourAccessKeyID  -k yourAccessKeySecret