Use ossutil ls command to list buckets, objects, and parts - Object Storage Service

The ls command lists buckets, objects, and multipart upload parts in your Object Storage Service (OSS) account. Use it to audit storage usage, locate large objects, or identify incomplete uploads that are consuming storage and incurring charges.

Usage notes

Starting from ossutil 1.6.16, use ossutil as the binary name on any OS. For versions earlier than 1.6.16, use the OS-specific binary name. For details, see ossutil command reference.

Permissions

Alibaba Cloud accounts have full permissions by default. RAM users and RAM roles have no default permissions and must be granted access via a RAM policy or bucket policy.

API action	Description
`oss:ListBuckets`	Required to list buckets in an account
`oss:ListObjects`	Required to list objects in a specified bucket
`oss:ListObjectVersions`	Optional. Required when using `--all-versions`
`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`	The resource to list, in the format `oss://[bucket_name[/prefix]]`. If omitted, all accessible buckets in the current account are listed. `oss://bucket_name` lists all objects in the bucket recursively. `oss://bucket_name/prefix` lists all objects that match the prefix, recursively.
`-s, --short-format`	Lists only resource names, with no additional metadata.
`-d, --directory`	Non-recursive listing. Lists objects and first-level subdirectories (common prefixes ending with `/`) at the current path only.
`-m, --multipart`	Lists incomplete or aborted multipart upload tasks in the specified bucket. Incomplete parts occupy storage space and incur charges — check and clear them regularly.
`-a, --all-type`	Lists both objects and incomplete multipart upload parts.
`--limited-num`	Maximum number of results to return per request. Use with `--marker` to paginate through large listings and avoid request timeouts.
`--marker`	Starts listing from the specified marker. Use with `--limited-num` for pagination.
`--upload-id-marker`	Resumes listing incomplete multipart uploads from the specified UploadId.
`--payer`	Set to `requester` to have the requester pay for traffic and request fees.
`--include`	Lists objects matching the specified wildcard pattern. See --include and --exclude options.
`--exclude`	Excludes objects matching the specified wildcard pattern. See --include and --exclude options.
`--all-versions`	Lists all historical versions of objects. Valid only for versioning-enabled buckets.
`--version-id-marker`	Resumes listing object versions from the specified version ID. Valid only for versioning-enabled buckets.

For additional options, see Common options.

Output fields

The object listing includes an ETag field for content verification:

Objects uploaded via PutObject: the ETag is the MD5 hash of the object content.
Objects created by other methods (such as multipart upload): the ETag is a unique value, not the MD5 hash.

Examples

List all buckets

Run ls without arguments to list all accessible buckets in your account. The output shows each bucket's creation time, region, storage class, and name.

ossutil ls

Alternatively:

ossutil ls oss://

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 short format

Use -s to list only bucket names, without timestamps, regions, or storage classes.

ossutil ls -s

Output:

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

Paginate through buckets

When you have many buckets, use --limited-num and --marker together to page through results. The following command returns two buckets alphabetically after examplebucketA.

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

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 bucket

List all objects in examplebucket. The output includes each object's last modified time, size in bytes, storage class, ETag, and full object name.

ossutil ls oss://examplebucket

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

List objects by prefix

List objects in examplebucket whose names start with example. The prefix acts as a path filter, not a directory boundary.

ossutil ls oss://examplebucket/example

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

Filter objects by file type

Use --include to list objects matching a wildcard pattern. The following command lists all .mp4 files in examplebucket.

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

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

List objects non-recursively

Use -d to list only the objects and first-level subdirectories in the root of examplebucket, without descending into subdirectories.

ossutil ls oss://examplebucket -d

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 versioning-enabled buckets, use --all-versions to list every stored version of every object. The output adds VERSIONID, IS-LATEST, and DELETE-MARKER columns. Delete markers (objects with no size and DELETE-MARKER: true) indicate objects that were deleted while versioning was enabled.

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

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 specific object

To see all versions of a single object, specify the full object name with --all-versions.

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

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 incomplete multipart uploads

Use -m to list all incomplete parts in examplebucket — uploads that were interrupted or abandoned. Each entry shows the initiation time, UploadId, and the target object name. These parts occupy storage and incur charges, so delete them periodically.

ossutil ls oss://examplebucket -m

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 incomplete parts together

Use -a to list both completed objects and incomplete multipart upload parts in a single command. The output shows the object listing first, followed by the multipart upload listing.

ossutil ls oss://examplebucket -a

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 objects in a bucket owned by another account

To list resources in a bucket that belongs to a different Alibaba Cloud account, specify the endpoint, AccessKey ID, and AccessKey Secret for that account.

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