The ossutil sync command copies new and updated objects from an OSS bucket path to an on-premises folder. It does not delete local files that no longer exist in OSS unless you use --delete.
Prerequisites
Before you begin, ensure that you have:
The
oss:GetObjectandoss:ListObjectspermissions on the bucket. For details, see Grant custom access policies to a RAM userossutil installed and configured with valid credentials
Syntax
ossutil sync <cloud_url> <file_url> [options]| Parameter | Type | Description |
|---|---|---|
cloud_url | string | The OSS source path. Format: oss://bucketname/path/. If the path does not end with /, ossutil adds one automatically. Example: oss://examplebucket/exampledir/ |
file_url | string | The local destination folder. Example: /localfolder/ (Linux) or D:\localfolder\ (Windows) |
Examples
Download all objects from an OSS path to a local folder:
ossutil sync oss://examplebucket/localdir/ D:\destdir\Only objects that are missing locally or differ in size or modification time are downloaded. The output lists each transferred object:
download: oss://examplebucket/localdir/report.pdf to D:\destdir\report.pdf
download: oss://examplebucket/localdir/data.csv to D:\destdir\data.csvSync and move deleted objects to a backup folder instead of leaving them locally:
ossutil sync oss://examplebucket/localdir/ D:\destdir\ --delete --backup-dir backup/Without --backup-dir, --delete permanently removes local files that no longer exist in OSS.
--delete can result in permanent data loss. Test on a small subset first before applying it to production data.
Usage notes
`-u, --update`: Sends at least one HEAD request per object to check the modification time, even if the object already exists locally. In scenarios with few data changes, this generates many requests and may incur extra request fees. If a local file has the same modification time as the OSS object, the file is still updated. Evaluate your use case before enabling this option.
`--max-sync-num`: The default is 2,000,000. The maximum is 5,000,000.
`--bigfile-threshold`: Objects larger than this threshold (default: 104,857,600 bytes) use multipart upload, download, or copy automatically.
Options
Sync behavior
| Option | Type | Description |
|---|---|---|
--delete | flag | Deletes local files that do not exist in OSS. Use with --backup-dir to preserve deleted files. |
--backup-dir | string | Moves files that would be deleted by --delete to this directory instead. |
-u, --update | flag | Skips local files that are newer than the OSS object. If the modification times are equal, the file is still updated. |
--ignore-existing | flag | Skips all local files that already exist, regardless of modification time. |
--size-only | flag | Transfers only objects whose size differs from the local file. |
--checksum | flag | Transfers only objects whose size and checksum (if available) differ from the local file. Valid only for object-to-object copies. |
--max-sync-num | int | Maximum number of objects to sync. Default: 2,000,000. Maximum: 5,000,000. |
Filtering
| Option | Type | Description |
|---|---|---|
--include | stringArray | Inclusion rules for paths or file names. |
--include-from | stringArray | Reads inclusion rules from a file. |
--exclude | stringArray | Exclusion rules for paths or file names. |
--exclude-from | stringArray | Reads exclusion rules from a file. |
--filter | stringArray | Filtering rules for paths or file names. |
--filter-from | stringArray | Reads filtering rules from a file. |
--files-from | stringArray | Reads a list of source object names from a file. Empty and commented lines are ignored. |
--files-from-raw | stringArray | Reads a list of source object names from a file. |
--min-size | SizeSuffix | Transfers only objects at or above this size. Default unit: bytes. Supports suffixes: B, K, M, G, T, P. 1 K = 1,024 B. |
--max-size | SizeSuffix | Transfers only objects at or below this size. Default unit: bytes. Supports suffixes: B, K, M, G, T, P. |
--min-age | Duration | Transfers only objects modified before the specified interval. Default unit: seconds. Example: --min-age 1h transfers only objects modified 1 hour ago or earlier. |
--max-age | Duration | Transfers only objects modified within the specified interval. Default unit: seconds. Example: --max-age 1h transfers only objects modified within the last hour. |
--min-mtime | Time | Transfers only objects modified after the specified UTC time. Format: 2006-01-02T15:04:05. |
--max-mtime | Time | Transfers only objects modified before the specified UTC time. Format: 2006-01-02T15:04:05. |
--start-after | string | Returns objects whose names are alphabetically after the specified value. |
--end-with | string | Returns objects whose names are alphabetically at or before the specified value. |
--metadata-include | stringArray | Inclusion rules for object metadata. |
--metadata-exclude | stringArray | Exclusion rules for object metadata. |
--metadata-filter | stringArray | Filtering rules for object metadata. |
--metadata-filter-from | stringArray | Reads object metadata filtering rules from a file. |
Performance
| Option | Type | Description |
|---|---|---|
-j, --job | int | Number of concurrent tasks for multi-object operations. Default: 3. |
--parallel | int | Number of concurrent tasks for a single object. |
--bigfile-threshold | int | Size threshold (in bytes) above which multipart upload, download, or copy is used. Default: 104,857,600. |
--part-size | SizeSuffix | Part size for resumable operations. Default: calculated from file size. Range: 100 KiB–5 GiB. |
--page-size | int | Maximum number of objects listed per page during batch operations. Default: 1,000. Range: 1–1,000. |
--no-progress | flag | Suppresses the progress bar. |
Object properties
| Option | Type | Description |
|---|---|---|
--acl | string | Access control list (ACL) of the object. Values: private, public-read, public-read-write, default (inherits bucket ACL). |
--storage-class | string | Storage class of the object. Values: Standard, IA (Infrequent Access), Archive, ColdArchive, DeepColdArchive. |
--metadata | strings | User metadata of the object. Format: key=value. |
--metadata-directive | string | How to set metadata on the destination object. Values: COPY, REPLACE. |
--tagging | strings | Tags for the object. Format: key=value. |
--tagging-directive | string | How to set tags on the destination object. Values: COPY, REPLACE. |
--copy-props | string | Properties to copy from the source object. Values: none, metadata, default. |
--cache-control | string | Caching behavior when the object is downloaded by a browser. |
--content-disposition | string | How the object is displayed. |
--content-encoding | string | Encoding format of the object. |
--content-type | string | Content type of the object. |
--expires | string | Absolute expiration time for cached content. |
Other options
| Option | Type | Description |
|---|---|---|
-d, --dirs | flag | Lists files and immediate subdirectories only, without recursing into subdirectories. |
--encoding-type | string | Encoding type for object names or file names. Valid value: url. |
-f, --force | flag | Proceeds without a confirmation prompt. |
--list-objects | flag | Uses the ListObjects API to list objects. |
--checkpoint-dir | string | Directory for checkpoint files used in resumable operations. Default: .ossutil_checkpoint/. |
-r, --recursive | flag | Applies the operation recursively to all matching objects in the bucket. |
--request-payer | string | Payment method for the request. Set to requester to enable pay-by-requester mode. |
For the full list of options, see Command-line options.
What's next
cp (Copy objects) — Use
cpfor one-time transfers without sync behavior.