All Products
Search

This Product

    Object Storage Service:ls (List account-level resources)

    Document Center

    Object Storage Service:ls (List account-level resources)

    Last Updated:Mar 19, 2026

    Use the ls command to list your OSS buckets, objects, and incomplete multipart upload parts. Common use cases include auditing storage usage, locating large files for cleanup, and scripting object inventory workflows.

    Prerequisites

    Before you begin, ensure that you have the following Resource Access Management (RAM) permissions:

    OperationRequired permission
    List bucketsoss:ListBuckets
    List objectsoss:ListObjects
    List object versionsoss:ListObjectVersions
    List partsoss:ListParts and oss:ListMultipartUploads

    For instructions on granting these permissions, see Attach a custom policy to a RAM user.

    Syntax

    ossutil ls [oss://bucket[/prefix]] [options]

    Options

    OptionTypeDescription
    --all-versions/Lists all versions of objects.
    -d, --dirs/Lists only the top-level files and subdirectories in the specified directory, not recursively.
    --encoding-typestringSpecifies the encoding type for object names or filenames. Valid value: url.
    --end-withstringLists only objects whose names are lexicographically less than or equal to the specified value.
    --excludestringArrayExcludes files and paths that match the specified rules.
    --exclude-fromstringArrayReads exclude rules from the specified rule file.
    --files-fromstringArrayReads the list of source filenames from a file. Empty lines and lines starting with a hash (#) are ignored.
    --files-from-rawstringArrayReads the list of source filenames from a file.
    --filterstringArraySpecifies one or more filter rules for file paths or names.
    --filter-fromstringArrayReads filter rules from the specified rule file.
    -f, --force/Forces the operation and suppresses confirmation prompts.
    --includestringArrayIncludes only files and paths that match the specified rules.
    --include-fromstringArrayReads include rules from the specified rule file.
    --limited-numintSpecifies the maximum number of results to return.
    --list-objects/Lists objects by using the ListObjects (GetBucket) API operation.
    --max-ageDurationLists only files last modified within the specified duration. The default unit is seconds; use the h suffix for hours. For example, --max-age 1h lists files modified within the last hour.
    --max-mtimeTimeLists only files modified before the specified time. Use UTC format: 2006-01-02T15:04:05Z.
    --max-sizeSizeSuffixLists only objects no larger than the specified size. The default unit is bytes. Valid suffixes: B, K, M, G, T, P. Note: 1 K = 1 kibibyte (1,024 bytes).
    --metadata-excludestringArraySpecifies exclude rules for object metadata.
    --metadata-filterstringArraySpecifies filter rules for object metadata.
    --metadata-filter-fromstringArrayReads object metadata filter rules from the specified rule file.
    --metadata-includestringArraySpecifies include rules for object metadata.
    --min-ageDurationLists only files last modified more than the specified duration ago. The default unit is seconds; use the h suffix for hours. For example, --min-age 1h lists files not modified in the last hour.
    --min-mtimeTimeLists only files modified after the specified time. Use UTC format: 2006-01-02T15:04:05Z. For example, --min-mtime "2006-01-02T15:04:05Z" lists files modified after 15:04:05 on January 2, 2006.
    --min-sizeSizeSuffixLists only objects no smaller than the specified size. The default unit is bytes. Valid suffixes: B, K, M, G, T, P. Note: 1 K (KiB) = 1,024 bytes.
    --multipart/Lists incomplete multipart upload tasks.
    --page-sizeintSpecifies the maximum number of objects to return per page in a batch operation. Default: 1,000. Valid range: 1–1,000.
    -r, --recursive/Recursively lists all matching objects. Without this option, the command lists only top-level items in the specified path.
    --request-payerstringSpecifies the payer for the request. If the bucket uses Requester Pays mode, set this to requester.
    --resource-group-idstringSpecifies the ID of the resource group.
    --short-format/Displays output in short format. Long format is used by default.
    --start-afterstringLists only objects whose names are lexicographically greater than the specified value.

    For a full list of global options, see Command-line options.

    Examples

    List all buckets

    ossutil ls

    List all objects in a bucket

    ossutil ls oss://examplebucket

    List objects with a specific prefix

    ossutil ls oss://examplebucket/dir

    List only top-level items in a directory

    To see just the immediate files and subdirectories under dir/ without recursing into subdirectories:

    ossutil ls oss://examplebucket/dir -d

    Limit the number of results

    Return the first 100 objects under the dir/ prefix:

    ossutil ls oss://examplebucket/dir --limited-num 100

    Filter objects by name pattern

    List all .txt files under dir1/ and dir2/ (including their subdirectories):

    ossutil ls oss://examplebucket/ --include "/dir1/**.txt" --include "/dir2/**.txt"

    Filter objects by modification time

    List all files in dir1/ and dir2/ modified within the last three days:

    ossutil ls oss://examplebucket --include "/dir1/**" --include "/dir2/**" --max-age 3d

    Output results in JSON format

    List all buckets and format the output as JSON for programmatic processing:

    ossutil ls --output-format json