All Products
Search

This Product

    Object Storage Service:View options

    Document Center

    Object Storage Service:View options

    Last Updated:Mar 01, 2026

    Run ossutil -h to display all options supported by ossutil.

    For ossutil 1.6.16 and later, use ossutil as the binary name on all operating systems. Earlier versions require an OS-specific binary name. For more information, see ossutil command reference.

    Command syntax

    ossutil -h

    To view the options for a specific command, run ossutil help [command]. For example:

    ossutil help cp

    Common options

    The following options apply to most ossutil commands.

    OptionDescription
    -c, --config-filePath to the ossutil configuration file. ossutil reads this file on startup. To manage buckets across different Alibaba Cloud accounts, create multiple configuration files and specify one with this option.
    -e, --endpointEndpoint of the bucket. Use this option to manage buckets across regions. For more information, see Regions and endpoints.
    -i, --access-key-idAccessKey ID for accessing Object Storage Service (OSS). Use this option to manage buckets that belong to different Alibaba Cloud accounts.
    -k, --access-key-secretAccessKey secret for accessing OSS. Use this option to manage buckets that belong to different Alibaba Cloud accounts.
    -p, --passwordAccessKey secret for accessing OSS, entered interactively from the keyboard. This value overrides the AccessKey secret configured by other methods.
    --loglevelLog level for the ossutil.log file generated in the current working directory. Default: no log file is generated. Valid values: info -- logs operations. Example: ossutil [command] --loglevel=info. debug -- logs HTTP requests, responses, and raw signature strings for troubleshooting. Example: ossutil [command] --loglevel=debug.
    --proxy-host, --proxy-user, --proxy-pwdProxy server settings. Specify all three options to route ossutil traffic through a proxy. --proxy-host: proxy URL. Supports HTTP, HTTPS, and SOCKS5. --proxy-user: proxy username. Default: empty. --proxy-pwd: proxy password. Default: empty. Example: ossutil ls oss://bucket1 --proxy-host http://47.88.**:3128 --proxy-user test --proxy-pwd test
    --modeCredential type for authentication. Valid values: AK -- AccessKey ID and AccessKey secret. StsToken -- Security Token Service (STS) token. RamRoleArn -- AssumeRole through Resource Access Management (RAM). EcsRamRole -- password-free authentication from an Elastic Compute Service (ECS) instance. Default: default authentication logic.
    --ecs-role-nameRAM role name for EcsRamRole authentication.
    --token-timeoutValidity period of the token obtained through AssumeRole in RamRoleArn authentication. Default: 3600. Unit: seconds.
    --ram-role-arnAlibaba Cloud Resource Name (ARN) of the RAM role for RamRoleArn authentication.
    --role-session-nameSession name for RamRoleArn authentication.
    --read-timeoutClient read timeout. Default: 1200. Unit: seconds.
    --connect-timeoutClient connection timeout. Default: 120. Unit: seconds.
    --sts-regionRegion for the STS endpoint. Example: cn-hangzhou. For all supported regions, see Endpoints. Default: sts.aliyuncs.com.
    --skip-verify-certSkips server certificate verification.
    --uaCustom User-Agent header value. The specified value is appended to the default ossutil User-Agent string. To view the full User-Agent value, use --loglevel debug.

    Command-specific options

    The following options are available for specific ossutil commands.

    OptionDescription
    -s, --short-formatDisplays items in short format. Default: long format.
    --bigfile-thresholdObject size threshold for resumable upload. Default: 104857600 (100 MB). Valid values: 0 to 9223372036854775807. Unit: bytes.
    --aclAccess control list (ACL) to apply.
    --rangeByte range of the object to download. Bytes are numbered starting from 0. Formats: 3-9 -- bytes 3 through 9 (inclusive). 3- -- byte 3 through end of object. -9 -- byte 0 through byte 9 (inclusive).
    --all-versionsApplies the operation to all versions of an object.
    --typeAlgorithm for data verification. Default: crc64. Valid values: crc64, md5.
    -v, --versionDisplays the ossutil version.
    -u, --updatePerforms an incremental operation.
    --originValue of the Origin header in an HTTP request.
    --upmodeUpload method for the probe command. Default: normal. Valid values: normal -- simple upload. append -- append upload. multipart -- multipart upload.
    --sse-algorithmServer-side encryption algorithm for the bucket. Valid values: KMS -- encryption with keys managed by Key Management Service (KMS) (SSE-KMS). AES256 -- encryption with keys managed by OSS (SSE-OSS).
    --includeIncludes only objects that match the specified pattern. Example: *.jpg includes all JPG objects. See --include and --exclude pattern behavior.
    --excludeExcludes objects that match the specified pattern. Example: *.txt excludes all TXT objects. See --include and --exclude pattern behavior.
    -r, --recursivePerforms the operation recursively on all matching objects in the bucket. Without this option, only the object specified in the URL is affected.
    --addrNetwork address for connectivity checks. ossutil runs a ping to this address. Default: www.aliyun.com.
    --kms-masterkey-idCustomer master key (CMK) ID for KMS encryption.
    --version-idVersion ID of the object.
    --version-id-markerStarting position for listing object versions. Lists versions with IDs alphabetically after this value. Requires versioning to be enabled on the bucket.
    -m, --multipartApplies the operation to incomplete multipart upload tasks in the bucket.
    -d, --directoryReturns only objects and subdirectories in the current directory.
    --payerRequest payer. Set to requester to enable pay-by-requester mode.
    --maxupspeedMaximum upload speed. Default: 0 (unlimited). Unit: KB/s.
    --maxdownspeedMaximum download speed. Default: 0 (unlimited). Unit: KB/s.
    --retry-timesNumber of retries when an error occurs. Default: 10. Valid values: 1 to 500. Retries are performed immediately after an error.
    --downloadChecks network connectivity by downloading an object from the bucket using its URL.
    -j, --jobsNumber of concurrent tasks across multiple objects. Default: 3. Valid values: 1 to 10000.
    -a, --all-typeApplies the operation to both objects and incomplete multipart upload tasks in the bucket.
    --disable-empty-refererBlocks requests with an empty Referer header.
    --methodHTTP request method. Valid values: PUT, GET, DELETE.
    --output-dirDirectory for output files, such as error reports generated by the cp command during batch operations. Default: ossutil_output in the current directory.
    --metaObject metadata in [header:value#header:value...] format. Example: Cache-Control:no-cache#Content-Encoding:gzip.
    --objectObject name for the probe command.
    --end-timeLinux/UNIX timestamp. Objects with a last modified time later than this value are ignored.
    --limited-numMaximum number of results to return.
    -L, --languageLanguage for ossutil output. Default: CH. Valid values: CH -- Chinese (requires UTF-8 encoding). EN -- English.
    --deleteDeletes the specified buckets, objects, or parts.
    -b, --bucketSpecifies that the delete operation targets a bucket.
    --disable-crc64Disables CRC-64 verification during data transfer. By default, CRC-64 is enabled.
    --uploadChecks network connectivity by uploading a local file to the bucket.
    --part-sizePart size for multipart operations. By default, ossutil calculates an appropriate size based on the object. Valid values: 1 to 9223372036854775807. Unit: bytes.
    --timeoutValidity period of a signed URL. Default: 60. Valid values: 0 to 9223372036854775807. Unit: seconds.
    --checkpoint-dirDirectory for storing checkpoint data during resumable upload, download, or copy operations. If a task fails, ossutil creates a .ossutil_checkpoint directory and saves checkpoint data there. On success, ossutil deletes the directory. If you specify a custom directory, make sure it can be deleted.
    --urlObject URL.
    --markerStarting position for list operations. Items (buckets, objects, or parts) with names alphabetically after this value are listed.
    -f, --forceForces the operation without prompting for confirmation.
    --snapshot-pathDirectory for storing snapshots of uploaded or downloaded objects. When specified, ossutil reads snapshot data and performs incremental uploads or downloads. Usage notes: Use this option to accelerate incremental uploads or downloads of large numbers of objects. Not supported for copy operations. This option records the last modified time of objects locally. Between runs, objects in OSS must not be modified by other users. If objects may change between runs, use --update instead for incremental operations. Snapshot data is not automatically deleted. Remove outdated snapshots manually. Reading and writing snapshot data adds overhead. For small object counts or good network conditions, use --update instead. Both --update and --snapshot-path can be combined. ossutil checks snapshots first, then falls back to --update logic.
    --start-timeLinux/UNIX timestamp. Objects with a last modified time earlier than this value are ignored.
    --storage-classStorage class of the object. Default: Standard. Valid values: Standard -- for frequently accessed data. IA -- Infrequent Access. Minimum storage: 30 days, minimum billable size: 64 KB. Supports real-time access. Data retrieval fees apply. Archive -- for long-term storage. Minimum storage: 60 days, minimum billable size: 64 KB. Requires restoration (approximately 1 minute). Data retrieval fees apply. ColdArchive -- for rarely accessed long-term storage. Minimum storage: 180 days, minimum billable size: 64 KB. Requires restoration (time varies by object size and restoration mode). Data retrieval fees apply.
    -t, --sts-tokenSTS token for temporary access to OSS. Required only for STS-based authentication. This value overrides the token in the configuration file. For more information, see Authorized third-party upload.
    --parallelNumber of concurrent operations on a single object. Default: auto-calculated based on operation type and object size. Valid values: 1 to 10000.
    --partition-downloadPartition to download, in partition_number:total_partitions format. Example: 1:5 downloads partition 1 of 5. Partitions are numbered starting from 1, and partitioning is determined by ossutil. Use this option to split an object across multiple concurrent ossutil commands, each downloading its own partition.
    --bucketnameBucket name.
    --encoding-typeEncoding type for the object key after oss://bucket_name. Valid value: url. Default: no encoding.
    --originValue of the Origin header in an HTTP request, specifying the source domain for cross-origin requests.
    --acr-methodValue of the Access-Control-Request-Method header. Valid values: GET, PUT, POST, DELETE, HEAD.
    --acr-headersValue of the Access-Control-Request-Headers header. Specifies non-standard request headers. Separate multiple headers with commas and enclose them in double quotes. Example: --acr-headers "header1,header2,header3".
    --upload-id-markerStarting position for listing multipart upload tasks. Lists tasks with upload IDs alphabetically after this value.
    -h, --helpDisplays help information for a command.
    --trafic-limitHTTP access speed limit for signed URLs. Default: 0 (unlimited). Valid values: 819200 to 838860800 (100 KB/s to 100 MB/s). Unit: bit/s.
    --local-hostLocal IP address for ossutil to use with the cp command.
    --enable-symlink-dirUploads subdirectories that symbolic links point to. By default, these subdirectories are not uploaded. Use the probe command to check whether a symlinked target is also a symbolic link.
    --only-current-dirUploads, downloads, or copies only objects in the current directory. Ignores subdirectories and their contents.
    --disable-dir-objectPrevents generating an OSS object for uploaded directories. The directory structure is maintained in the OSS console, but deleting all objects in a directory also deletes the directory.
    --probe-itemItem to check with the probe command. Valid values: upload-speed -- checks upload bandwidth. download-speed -- checks download bandwidth. cycle-symlink -- checks whether a local symbolic link points to itself.
    --redundancy-typeData redundancy type of the bucket. Default: LRS. Valid values: LRS -- locally redundant storage. Stores copies of each object across different devices within the same zone. ZRS -- zone-redundant storage. Stores copies across multiple zones in the same region, providing availability even if a zone becomes unavailable.
    --disable-encode-slashPrevents encoding forward slashes (/) in URLs.
    --disable-all-symlinkIgnores all symbolic links and their target subdirectories during upload.
    --taggingObject tags to apply during upload or copy. Example: "abc=1&bcd=2&...".
    --disable-ignore-errorStops batch operations when an error occurs, instead of ignoring errors.
    --block-sizeUnit for displaying the total object size within a bucket or directory. Valid values: KB, MB, GB, TB. Default: bytes.
    Important

    Available in ossutil 1.7.3 and later.

    --include and --exclude pattern behavior

    Left-to-right evaluation

    A rule can contain multiple --include and --exclude conditions. ossutil evaluates conditions from left to right to determine the final result. For example, given a test.txt object in the target directory:

    • Rule 1: --include "*test*" --exclude "*.txt" ossutil first evaluates --include "*test*" and includes test.txt because it matches. Then ossutil evaluates --exclude "*.txt" and excludes test.txt because it matches *.txt. Result: excluded.

    • Rule 2: --exclude "*.txt" --include "*test*" ossutil first evaluates --exclude "*.txt" and excludes test.txt. Then ossutil evaluates --include "*test*" and includes test.txt because it matches. Result: included.

    • Rule 3: --include "*test*" --exclude "*.txt" --include "te?t.txt" ossutil evaluates --include "*test*" (included), then --exclude "*.txt" (excluded), then --include "te?t.txt" (included). Result: included.

    Wildcard patterns

    PatternDescriptionExample
    *Matches any number of characters.*.txt matches all TXT files.
    ?Matches a single character.abc?.jpg matches abc1.jpg, abcX.jpg, etc.
    [sequence]Matches any character in the sequence.abc[1-5].jpg matches abc1.jpg through abc5.jpg.
    [!sequence]Matches any character not in the sequence.abc[!0-7].jpg matches objects like abc8.jpg and abc9.jpg, but not abc0.jpg through abc7.jpg.

    Limitations

    Directory paths cannot be specified in --include or --exclude patterns. For example, the following command produces the error --include or --exclude does not support format containing dir info:

    ossutil cp oss://examplebucket/destfolder/ localfolder/ --include "dir/"