The ls command is used to list buckets, objects, or parts.

Note The commands described in this topic apply to Linux. To use the commands in other systems, replace ./ossutil in the command with the actual executable program name. For example, you can use the help command in 32-bit Windows systems by running ossutil32.exe help.

Command syntax

./ossutil ls [oss://bucket[/prefix]] [-s] [-d] [-m] [--limited-num num] [--marker marker] [--upload-id-marker umarker] [--payer requester] [--include include-pattern] [--exclude exclude-pattern]  [--version-id-marker id_marker] [--all-versions]  [-c file]

Examples

  • List buckets 
    ./ossutil ls
CreationTime                                 Region    StorageClass    BucketName
2016-10-2116:18:37 +0800 CST       oss-cn-hangzhou         Archive    oss://bucket1
2016-12-0115:06:21 +0800 CST       oss-cn-hangzhou        Standard    oss://bucket2
2016-07-2010:36:24 +0800 CST       oss-cn-hangzhou              IA    oss://bucket3
Bucket Number is:3
0.252174(s) elapsed
    Note You can also use the ./ossutil ls oss:// command to list buckets.
  • List buckets by page 
    ./ossutil ls oss:// --limited-num=${num} --marker=${bucketname}
    When the number of buckets is large, you can use the --limited-num and --marker options to list buckets by page.
    • --limited-num is used to control the number of entries displayed on each page.
    • --marker specifies the bucket from which you want to start listing. The results displayed by ossutil are returned starting from the first bucket in alphabetical order after the value of the marker. In most cases, this parameter value is set to the last bucket name displayed on the previous page.
    The following code provides an example on how to list the first two buckets by page: 
    ./ossutil ls oss:// --limited-num=1 -s 
oss://bucket1
Bucket Number is:1
0.303869(s) elapsed
./ossutil ls oss:// --limited-num=1 -s --marker=bucket1
oss://bucket2
Bucket Number is:1
0.257636(s) elapsed
  • List all objects in a specified bucket 
    ./ossutil ls oss://bucket1
LastModifiedTime                    Size(B)  StorageClass   ETAG                                    ObjectName
2016-12-0115:06:37 +0800 CST      10363812      Standard   61DE142E5AFF9A6748707D4A77BFBCFB        oss://bucket1/a1
2016-12-0115:06:42 +0800 CST      10363812      Standard   61DE142E5AFF9A6748707D4A77BFBCFB        oss://bucket1/a2
2016-12-0115:06:45 +0800 CST      10363812      Standard   61DE142E5AFF9A6748707D4A77BFBCFB        oss://bucket1/a3
Object Number is:3
0.007379(s) elapsed
  • List all objects by page 
    ./ossutil ls oss://bucket --limited-num=${num} --marker=${obj}
    Similar to the operation of listing buckets by page, you can use the --limited-num and --marker options to list objects by page. The following code provides an example of how to list the first two objects in the bucket1 root directory: 
    ./ossutil ls oss://bucket1 --limited-num=1
LastModifiedTime                    Size(B)  StorageClass   ETAG                                    ObjectName
2016-12-0115:06:37 +0800 CST      10363812      Standard   61DE142E5AFF9A6748707D4A77BFBCFB        oss://bucket1/a1
Object Number is:1
0.007379(s) elapsed
$./ossutil ls oss://bucket1 --limited-num=1 --marker=a1
LastModifiedTime                    Size(B)  StorageClass   ETAG                                    ObjectName
2016-12-0115:06:42 +0800 CST        11673      Standard    D41D8CD98F00B204E9800998ECF8427E       oss://bucket1/a2
Object Number is:1
0.008392(s) elapsed
  • List UploadIDs.
    You can add the -m option to the ls command to list upload IDs of all incomplete multipart upload tasks initiated to objects with a specified prefix. 
    ./ossutil ls oss://bucket1/obj1 -m
InitiatedTime                     UploadID                               ObjectName
2017-01-13 03:45:26 +0000 CST     15754AF7980C4DFB8193F190837520BB    oss://bucket1/obj1
2017-01-13 03:43:13 +0000 CST     2A1F9B4A95E341BD9285CC42BB950EE0    oss://bucket1/obj1
UploadId Number is: 2
0.070070(s) elapsed
  • List all objects and incomplete multipart upload tasks
    You can add the -a option to the ls command to list the upload IDs of all incomplete multipart upload tasks initiated to objects with a specified prefix and the uploaded objects with the prefix. 
    ./ossutil ls oss://bucket1 -a 
LastModifiedTime                    Size(B)  StorageClass   ETAG                                    ObjectName
2015-06-0514:06:29 +0000 CST        201933      Standard   7E2F4A7F1AC9D2F0996E8332D5EA5B41        oss://bucket1/dir1/obj11
2015-06-0514:36:21 +0000 CST        201933      Standard   6185CA2E8EB8510A61B3A845EAFE4174        oss://bucket1/obj1
2016-04-0814:50:47 +0000 CST       6476984      Standard   4F16FDAE7AC404CEC8B727FCC67779D6        oss://bucket1/sample.txt
Object Number is:3
InitiatedTime                     UploadID                           ObjectName
2017-01-1303:45:26 +0000 CST     15754AF7980C4DFB8193F190837520BB    oss://bucket1/obj1
2017-01-1303:43:13 +0000 CST     2A1F9B4A95E341BD9285CC42BB950EE0    oss://bucket1/obj1
2017-01-1303:45:25 +0000 CST     3998971ACAF94AD9AC48EAC1988BE863    oss://bucket1/obj2
2017-01-2011:16:21 +0800 CST     A20157A7B2FEC4670626DAE0F4C0073C    oss://bucket1/tobj
UploadId Number is:4
0.191289(s) elapsed
  • Display the listed results in short format 
    ./ossutil ls oss://bucket1 -s
oss://bucket1/a1
oss://bucket1/a2
oss://bucket1/a3
Object Number is:3
0.007379(s) elapsed
  • List buckets in the form of directories

    You can use the -d option to list objects and subdirectories in the current directory, rather than recursively displaying all objects in all subdirectories. Example: 

    ./ossutil ls oss://bucket1 -s -d
oss://bucket1/obj1
oss://bucket1/sample.txt
oss://bucket1/dir1/
Object and Directory Number is:3 
0.119884(s) elapsed
  • List objects or subdirectories with a specific prefix in the current directory 
    ./ossutil ls oss://bucket1/test -d
oss://bucket1/test.jpg
oss://bucket1/test/
Object and Directory Number is: 2
  • List buckets in pay-by-requester mode 
    ./ossutil ls oss://bucket --payer=requester
  • List all versions of all objects in a versioning-enabled bucket 
    ./ossutil ls oss://bucket1 --all-versions
LastModifiedTime                   Size(B)  StorageClass  ETAG                                  VERSIONID                                                           IS-LATEST   DELETE-MARKER  ObjectName
2019-06-11 10:54:51 +0800 CST            0                                                      CAEQARiBgICUsOuR2hYiIDI3NWVjNmEyYmM0NTRkZWNiMTkxY2VjMDMwZjFlMDA3    true        true           oss://bucket1/test1.jpg
2019-06-11 11:03:37 +0800 CST            0                                                      CAEQARiBgIDZtvuR2hYiIDNhYjRkN2M5NTA5OTRlN2Q4YTYzODQwMzQ4NDYwZDdm    true        true           oss://bucket1/test.jpg
2019-06-11 10:53:46 +0800 CST       118076      Standard  FFDB300F053AAF06F4C4C58A4869C427      CAEQARiBgID8rumR2hYiIGUyOTAyZGY2MzU5MjQ5ZjlhYzQzZjNlYTAyZDE3MDRk    false       false          oss://bucket1/test1.jpg
2019-06-11 11:02:05 +0800 CST       345374      Standard  078A9852BCF81DC4811E6EDCBFD121BE      CAEQARiBgICNz_iR2hYiIGJjZTBjNDQxYWRhNTQ2ZTNiNmMzYzQ1YzMzMDA5ZjUw    false       false          oss://bucket1/test.jpg
Object Number is: 4

0.692000(s) elapsed
  • List all versions of a specific object in a versioning-enabled bucket 
    ./ossutil ls oss://bucket1/test.jpg --all-versions
LastModifiedTime                   Size(B)  StorageClass  ETAG                                  VERSIONID                                                           IS-LATEST   DELETE-MARKER  ObjectName
2019-06-11 11:03:37 +0800 CST            0                                                      CAEQARiBgIDZtvuR2hYiIDNhYjRkN2M5NTA5OTRlN2Q4YTYzODQwMzQ4NDYwZDdm    true        true           oss://bucket1/test.jpg
2019-06-11 11:02:05 +0800 CST       345374      Standard  078A9852BCF81DC4811E6EDCBFD121BE      CAEQARiBgICNz_iR2hYiIGJjZTBjNDQxYWRhNTQ2ZTNiNmMzYzQ1YzMzMDA5ZjUw    false       false          oss://bucket1/test.jpg
Object Number is: 2

0.361000(s) elapsed

Common options

The following table describes the options you can add to the ls command to specify the items to be listed and how they can be listed.
Option Description
-s Lists items in short format.
-d Lists objects and subdirectories in the current directory, rather than recursively displaying all objects in all subdirectories.
-m Lists only incomplete multipart upload tasks in the bucket. Objects are not displayed.
-a Lists both objects and incomplete multipart upload tasks in the bucket.
--limited-num Specifies the maximum number of returned entries. This option can be used together with the --marker option to list objects by page.
--marker Specifies the bucket name, object name, or multipart upload ID from which you want to start listing.
--upload-id-marker Specifies the multipart upload ID from which you want to start listing.
--payer Specifies the payer of the request. If pay-by-requester is enabled, you can set this option to requester.
--encoding-type Specifies the method used to encode the object name. If this option is specified, this value must be url. If this option is not specified, the object name is not encoded. Bucket names cannot be URL-encoded.
--loglevel Specifies the log level. The default value is null, indicating that no log files are generated. Valid values:
  • info: generates prompt logs.
  • debug: generates detailed logs that contain corresponding HTTP request and response information.
--all-versions Lists all versions of a specified object. This option can only be used for objects in a bucket that has versioning enabled.
--version-id-marker Specifies the object version from which you want to start listing.
Note For more information about common options, see View all supported options.