All Products
Search

This Product

    Object Storage Service:Synchronize local files to OSS using the sync command

    Document Center

    Object Storage Service:Synchronize local files to OSS using the sync command

    Last Updated:Mar 20, 2026

    Use ossutil sync to incrementally upload a local folder to an OSS bucket. The command compares local files against the destination and uploads only what has changed, so repeated runs are fast and efficient.

    How it works

    ossutil sync compares the last modified time of files or uses snapshot information to incrementally identify and upload only the changed files.

    The command also supports snapshot-based comparison: store snapshot information with --snapshot-path, and subsequent sync runs use that snapshot for faster incremental detection.

    Sync vs. cp

    Behaviorsynccp
    Recursive by defaultYes — traverses all files and subdirectoriesNo — requires -r
    Delete extra files at destinationYes — use --deleteNot supported
    Sync a previous object versionNot supportedYes — use --version-id

    For usage and examples of the cp command, see cp (upload files).

    File limits

    ScenarioLimit
    Without --deleteNo limit
    With --delete1,000,000 files maximum. If exceeded, ossutil returns: over max sync numbers 1000000.

    Prerequisites

    Before you begin, make sure you have:

    • ossutil installed. For version 1.6.16 and later, use the binary directly without renaming it. For earlier versions, rename the binary first. See ossutil Command Reference

    • The following permissions granted to your RAM user or RAM role via a RAM policy or bucket policy

    API actionDescription
    oss:ListObjectsLists objects in the destination bucket to compare with local files
    oss:PutObjectUploads files to OSS
    oss:DeleteObject(Optional) Required when using --delete
    oss:PutObjectTagging(Optional) Required when using --tagging

    Command syntax

    ossutil sync file_url cloud_url [options]
    ParameterDescription
    file_urlPath to the local folder. For example, /localfolder/ on Linux or D:\localfolder\ on Windows.
    cloud_urlPath to the destination OSS folder. Format: oss://bucketname/path/. If you omit the trailing /, ossutil adds it automatically. For example, oss://examplebucket/exampledir/.

    Options

    OptionDefaultDescription
    -f, --force—Skips the overwrite confirmation prompt and forces the operation.
    -u, --update—Uploads a file only if it does not exist at the destination, or if the source file is newer than the destination file.
    --delete—Deletes files at the destination that are not present at the source, so the destination mirrors the source exactly. Enable versioning before using this option to protect against accidental data loss.
    --enable-symlink-dir—Includes symbolic link subdirectories in the sync.
    --disable-all-symlink—Ignores all symbolic link files and symbolic link subdirectories.
    --disable-ignore-error—Stops on errors during batch operations instead of skipping them.
    --only-current-dir—Syncs only the files in the top-level source directory; ignores all subdirectories.
    --output-dirossutil_output in the current directoryDirectory where ossutil writes error report files generated during batch sync.
    -bigfile-threshold100 MBFile size threshold in bytes above which ossutil uses resumable upload. Valid values: 0–9223372036854775807.
    --part-sizeAuto-calculatedPart size in bytes for multipart upload. Valid values: 1–9223372036854775807.
    --checkpoint-dir.ossutil_checkpointDirectory for resumable upload checkpoint data. ossutil creates this directory automatically on failure and deletes it after a successful upload. If you specify a custom directory, make sure it can be deleted.
    --encoding-typeNoneEncoding format for file names. Set to url to URL-encode file names.
    --snapshot-path—Directory where ossutil saves snapshot information. On the next sync run, ossutil reads this snapshot to perform incremental synchronization.
    --include—Includes only files matching the specified pattern. See include and exclude options.
    --exclude—Excludes files matching the specified pattern. See include and exclude options.
    --meta—Sets object metadata. Format: header:value#header:value. For example: Cache-Control:no-cache#Content-Encoding:gzip. See set-meta.
    --aclprivateAccess control list (ACL) for uploaded files. Valid values: default (inherit from bucket), private, public-read, public-read-write.
    --maxupspeed0 (unlimited)Maximum upload speed in KB/s.
    --disable-crc64—Disables CRC-64 data validation.
    --payer—Set to requester to enable requester pays for traffic and request fees.
    -j, --job3Number of concurrent tasks for multi-file operations. Valid values: 1–10000.
    --parallelAuto-determinedNumber of concurrent tasks for a single-file operation. Valid values: 1–10000.
    --retry-times10Number of retries on error. Valid values: 1–500.
    --tagging—Tags to apply to uploaded objects. Format: TagkeyA=TagvalueA&TagkeyB=TagvalueB.

    For other common options, see Common options.

    Examples

    The following examples use Linux. Adjust paths for your operating system.

    Initial state:

    Local                         examplebucket
└── localfolder/              └── destfolder/
    ├── d.txt                     ├── a.txt
    └── e.png                     ├── b.txt
                                  └── C/

    Sync a local folder to OSS

    Upload all files from localfolder/ to destfolder/. Files that already exist at the destination (a.txt, b.txt, and C/) are retained.

    ossutil sync localfolder/ oss://examplebucket/destfolder/

    On success, ossutil outputs the number of files synced, total size, and transfer speed:

    Succeed: Total num: 2, size: 750,081. OK num: 2(upload 2 files).

average speed 1641000(byte/s)

    After the sync, destfolder/ contains:

    destfolder/
├── a.txt
├── b.txt
├── d.txt
├── e.png
└── C/

    Remove extra files at the destination during sync

    Use --delete to delete objects at the destination that are not in the source. After this command, destfolder/ contains only the files currently in localfolder/.

    ossutil sync localfolder/ oss://examplebucket/destfolder/ --delete
    Warning

    Enable versioning on your bucket before using --delete to protect against accidental data loss.

    After the sync:

    destfolder/
├── d.txt
└── e.png

    Filter files by type

    Use --include and --exclude to control which files are synced.

    Sync only `.txt` files:

    ossutil sync localfolder/ oss://examplebucket/destfolder/ --include "*.txt"

    Only d.txt is uploaded. e.png is skipped. Existing files at the destination are unaffected.

    destfolder/
├── a.txt
├── b.txt
├── d.txt
└── C/

    Exclude `.txt` files:

    ossutil sync localfolder/ oss://examplebucket/destfolder/ --exclude "*.txt"

    Only e.png is uploaded. d.txt is skipped. Existing files at the destination are unaffected.

    destfolder/
├── a.txt
├── b.txt
├── e.png
└── C/

    Force-overwrite files with the same name

    By default, if a file at the destination has the same name as a file being uploaded, ossutil prompts for confirmation. Use -f to skip the prompt and overwrite without confirmation.

    ossutil sync localfolder/ oss://examplebucket/destfolder/ -f

    Sync to a bucket owned by another account

    Use -e, -i, and -k to provide credentials for a different Alibaba Cloud account. The following command syncs srcfolder/ to testfolder/ in examplebucket, which is in the China (Shanghai) region and owned by another account.

    Specify the endpoint for the region of your bucket. See Regions and endpoints.
    ossutil sync srcfolder/ oss://examplebucket/testfolder/ \
  -e oss-cn-shanghai.aliyuncs.com \
  -i LTAI4Fw2NbDUCV8zYUzA**** \
  -k 67DLVBkH7EamOjy2W5RVAHUY9H****
    Warning

    Embedding an AccessKey directly in a command is a security risk. For automated or long-running tasks, create a RAM role for the source account and grant it access to the destination account instead.

    What's next