cp (upload files)

Upload local files or directories to an OSS bucket with the cp command. Supports simple upload, resumable upload, batch upload, and incremental upload, with options for object metadata, storage class, and ACL.

How it works

The cp command selects an upload method based on file size:

Simple upload: Used when the file is smaller than the resumable upload threshold (default: 100 MB, configurable with --bigfile-threshold).
Resumable upload: Used when the file meets or exceeds the threshold. Interrupted uploads leave parts in the bucket. Clean up these parts periodically to avoid storage costs. You can manually delete parts or configure lifecycle rules for automatic deletion.

Note

Starting with ossutil v1.6.16, you can use ossutil as the binary name on all supported operating systems. In earlier versions, you must use the OS-specific binary name for your system. For more information, see ossutil command reference.

When you run this command in OSS on CloudBox:
1. Replace the endpoint in the configuration file with the CloudBox endpoint. For more information, see CloudBox endpoints.
2. Add the --sign-version, --region, and --cloudbox-id options to the examples in this topic. For more information about these three options, see Common options.

Permissions

An Alibaba Cloud account has full permissions by default. RAM users and RAM roles have no default permissions and require authorization through a RAM policy or a bucket policy.

API Action	Description
`oss:PutObject`	Uploads an object.
`oss:PutObjectTagging`	Required only when setting object tags during upload.
`kms:GenerateDataKey`	Required only when using Key Management Service (KMS) server-side encryption.
`kms:Decrypt`

Command syntax

ossutil cp file_url cloud_url [options]

Parameters and options:

Parameter	Description
file_url	The path of the local file. If the source is a directory, the path must end with a path separator (`/` or `\`). For example, `/localfolder/examplefile.txt` on a Linux system or `D:\localfolder\examplefile.txt` on a Windows system.
cloud_url	The path of the object, in the format `oss://bucket[/prefix]`. Example: `oss://examplebucket/examplefile.txt`.
-r, --recursive	Recursively uploads files and subdirectories. Without this option, only the specified object is processed.
-f --force	Forces the operation to proceed without a confirmation prompt.
-u, --update	Uploads only if the destination object is missing or older than the source file.
--maxupspeed	Maximum upload speed in KB/s. Default: 0 (unlimited).
--enable-symlink-dir	Uploads linked subdirectories. This option is disabled by default.
--disable-all-symlink	Ignores all symbolic links during upload.
--disable-ignore-error	Does not ignore errors during batch operations.
--only-current-dir	Uploads only the files in the specified source directory, ignoring its subdirectories.
--bigfile-threshold	The size threshold for a resumable upload. Unit: bytes. Default value: 100 MB Valid values: 0 to 9223372036854775807
--part-size	Part size in bytes. By default, ossutil calculates this based on file size. Range: 1 to 9223372036854775807
--checkpoint-dir	Directory for resumable upload records. By default, ossutil creates a `.ossutil_checkpoint` directory and deletes it after a successful upload. If you specify a custom directory, ensure it can be deleted.
--encoding-type	Filename encoding. Set to url to URL-encode filenames. Not encoded by default.
--include	Includes all files that meet the specified conditions. For more information about the syntax and examples, see Batch upload files that meet specified conditions.
--exclude	Excludes all files that meet the specified conditions. For more information about the syntax and examples, see Batch upload files that meet specified conditions.
--meta	The metadata of the file. This includes standard HTTP headers and user-defined metadata, which starts with `x-oss-meta-`. The metadata must be in the `header:value#header:value` format. Example: `Cache-Control:no-cache#Content-Encoding:gzip`. For more information about metadata supported by OSS, see Manage object metadata.
--acl	The access control list (ACL) of the file. Valid values: default (default): The ACL of the object is the same as the ACL of the bucket. private: Only the owner of the bucket can read and write the objects in the bucket. Other users cannot access the objects. public-read: Only the bucket owner can write to the objects in the bucket. Other users, including anonymous users, can read the objects. This can cause data leaks and unexpectedly high fees. If malicious users write illegal information to the objects, your legitimate rights and interests may be infringed. Do not configure this permission except in special scenarios. public-read-write: Anyone, including anonymous users, can read and write the objects in the bucket. This can cause data leaks and unexpectedly high fees. Use caution when you configure this permission.
--snapshot-path	Directory for upload snapshots. On subsequent uploads, ossutil reads this directory to perform incremental uploads.
--disable-crc64	Disables CRC-64 data validation. Enabled by default.
--disable-dir-object	Skips creating directory objects during upload.
--payer	Payment method. Set to requester to charge the requester for traffic and request fees.
--tagging	Tags to add during upload. Format: `TagkeyA=TagvalueA&TagkeyB=TagvalueB....`.
-j, --jobs	Concurrent tasks for multi-file operations. Default: 3. Valid values: 1 to 10000.
--parallel	Concurrent tasks for single-file operations. Valid values: 1 to 10000. Auto-determined based on operation type and file size if not set.
--start-time	A UNIX timestamp. Objects that were last updated before this time are ignored. Note Only ossutil 1.7.18 and later support this parameter. For more information about upgrading, see update (Upgrade ossutil).
--end-time	A UNIX timestamp. Objects that were last updated after this time are ignored. Note If you specify both `start-time` and `end-time`, the copy command is executed only for files that were last modified between the specified start and end times. Only ossutil 1.7.18 and later support this parameter. For more information about how to upgrade the version, see update (Upgrade ossutil).

For more information about other common options for this command, see Common options.

Adjust -j, --jobs and --parallel to tune performance. By default, ossutil calculates parallel based on file size. For batch large-file transfers, the actual concurrency is jobs × parallel.

If the machine has limited resources (bandwidth, memory, or CPU), reduce concurrency to 100 or less. Increase it if resources are underutilized.
Excessive concurrency can degrade performance or cause EOF errors. Tune -j, --jobs and --parallel based on your machine's resources. Start low and increase gradually to find the optimal value.

Examples

These examples use Linux. Adjust paths for your OS. The examples assume:

Bucket name: examplebucket
OSS directory: desfolder/
Local directory: localfolder/
Local file: examplefile.txt

Upload a single file

Upload a file to a directory. If no object name is specified, the original filename is used.
```
ossutil cp examplefile.txt oss://examplebucket/desfolder/
```
Upload a single file and use the --meta option to set the metadata of the file. The metadata must be in the header:value#header:value... format.
```
ossutil cp examplefile.txt oss://examplebucket/desfolder/examplefile.txt --meta=Cache-Control:no-cache#Content-Encoding:gzip
```

Batch uploads

Upload only the files in a folder
Add the -r option to the cp command to upload only the files from a local folder to a specified path in OSS.
```
ossutil cp -r localfolder/ oss://examplebucket/desfolder/
```
Upload files from a folder and specify a timestamp

Upload files from a local folder to a specified OSS path. The files must be modified between 10:09:18 (UTC+8) on October 31, 2023 and 12:55:58 (UTC+8) on October 31, 2023.
```
ossutil cp -r localfolder/ oss://examplebucket/desfolder/ --start-time 1698718158 --end-time 1698728158
```
Upload a folder and the files in it

Use the cp -r option to upload a local folder and its files. OSS creates a 0 KB object ending with / for each subdirectory, but not for the folder itself. To create a folder object, use the mkdir (create directories) command.
```
ossutil cp -r localfolder/ oss://examplebucket/desfolder/localfolder/
```
Upload a folder and skip existing files

To retry a failed batch upload, use --update (or -u) to skip already-uploaded files and perform an incremental upload:
```
ossutil cp -r localfolder/ oss://examplebucket/desfolder/ -u
```

Upload only the files in the current directory and ignore subdirectories

ossutil cp localfolder/ oss://examplebucket/desfolder/ --only-current-dir -r

Upload without generating an object for the directory

In OSS, directories are simulated by 0 KB objects ending with /. Use --disable-dir-object to skip creating these objects. The directory structure still appears in the OSS console but disappears when all files in it are deleted.
```
ossutil cp localfolder/ oss://examplebucket/desfolder/ --disable-dir-object -r
```

Upload files in a linked subdirectory

ossutil cp localfolder/ oss://examplebucket/desfolder/ --enable-symlink-dir -r

Ignore all linked subfiles and linked subdirectories during an upload

ossutil cp localfolder/ oss://examplebucket/desfolder/ -r --disable-all-symlink

Batch upload files that meet specified conditions

Use --include and --exclude to filter files during batch upload.

The --include and --exclude options support the following formats:

Asterisk (*): Matches any number of characters. For example, *.txt matches all TXT files.
Question mark (?): Matches a single character. For example, abc?.jpg matches all JPG files whose names are "abc" followed by a single character, such as abc1.jpg.
[sequence]: Matches any character in the sequence. For example, abc[1-5].jpg matches files named abc1.jpg to abc5.jpg.
[!sequence]: Matches any character outside the sequence. For example, abc[!0-7].jpg matches files whose names are not abc0.jpg to abc7.jpg.

A rule can contain multiple include and exclude conditions. ossutil evaluates them left to right. For a file named test.txt, different rule orderings produce different results.

Rule 1: --include "*test*" --exclude "*.txt" . When the rule matches --include "*test*", the result is that test.txt meets the condition. When the rule continues to match --exclude "*.txt", test.txt is excluded because its filename contains .txt. The final result is that test.txt does not meet the conditions.
Rule 2: --exclude "*.txt" --include "*test*". The file test.txt is excluded by the --exclude "*.txt" rule. However, the --include "*test*" rule then includes test.txt because its filename contains "test". As a result, test.txt is included.
Rule 3: --include "*test*" --exclude "*.txt" --include "te?t.txt" . First, the --include "*test*" rule includes test.txt. Next, the --exclude "*.txt" rule excludes test.txt. Finally, the --include "te?t.txt" rule includes test.txt. Therefore, test.txt is included.

Important

You cannot specify a directory format in the conditions. For example, --include "/usr/test/.jpg" is not supported.

The following are examples:

Upload all files in TXT format

ossutil cp localfolder/ oss://examplebucket/desfolder/ --include "*.txt" -r

Upload all files whose names contain abc and are not in JPG or TXT format

ossutil cp localfolder/ oss://examplebucket/desfolder/ --include "*abc*" --exclude "*.jpg" --exclude "*.txt" -r

Throttle uploads

Use --maxupspeed to limit upload speed in KB/s. Examples:

Upload a file and set the speed limit to 1 MB/s

ossutil cp examplefile.txt oss://examplebucket/desfolder/ --maxupspeed 1024

Upload a folder and set the speed limit to 1 MB/s

ossutil cp -r localfolder/ oss://examplebucket/desfolder/ --maxupspeed 1024

Upload and set object tags

Use --tagging to set object tags during upload. Separate multiple tags with ampersands (&). Example:

ossutil cp examplefile.txt oss://examplebucket/desfolder/ --tagging "abc=1&bcd=2&..."

Object tagging.

Upload and specify a storage class

Use --meta to set the storage class during upload. Valid values:

Standard: Standard
IA: Infrequent Access
Archive: Archive Storage
ColdArchive: Cold Archive
DeepColdArchive: Deep Cold Archive

Note

If you use OSS on CloudBox, only the Standard storage class is supported.

If no storage class is specified, the object inherits the bucket's storage class. For more information, see Storage Class.

The following are examples of uploading a file and specifying a storage class:

Upload a single file and set its storage class to Infrequent Access

ossutil cp examplefile.txt oss://examplebucket/desfolder/ --meta X-oss-Storage-Class:IA

Upload a folder and set the storage class of its files to Standard

ossutil cp localfolder/ oss://examplebucket/desfolder/ --meta X-oss-Storage-Class:Standard -r

Upload and specify an ACL

Use --acl to set the ACL of the uploaded file. Valid values:

default: inherits the ACL of the bucket (default)
private: private
public-read: public-read
public-read-write: Public read and write access

The following are examples:

Upload a single file and set its ACL to private

ossutil cp examplefile.txt oss://examplebucket/desfolder/ --acl private

Upload a folder and set the ACL of its files to public-read

ossutil cp localfolder/ oss://examplebucket/desfolder/ --acl public-read  -r

Upload and specify an encryption method

Specify a server-side encryption method during upload. Examples:

Note

In OSS on CloudBox scenarios, only AES256 encryption is supported.

Upload a file and specify SSE-OSS as the encryption method and AES256 as the encryption algorithm

ossutil cp examplefile.txt oss://examplebucket/desfolder/ --meta=x-oss-server-side-encryption:AES256

Upload a file and specify SSE-OSS as the encryption method and SM4 as the encryption algorithm

ossutil cp examplefile.txt oss://examplebucket/desfolder/ --meta=x-oss-server-side-encryption:SM4

Upload a file and specify SSE-KMS as the encryption method, specify AES256 as the encryption algorithm, and do not specify a CMK ID
```
ossutil cp examplefile.txt oss://examplebucket/desfolder/ --meta=x-oss-server-side-encryption:KMS
```
KMS encryption incurs a small key usage fee. KMS pricing.

Upload a file and specify SSE-KMS as the encryption method, SM4 as the encryption algorithm, and a CMK ID

ossutil cp examplefile.txt oss://examplebucket/desfolder/ --meta=x-oss-server-side-encryption:KMS#x-oss-server-side-data-encryption:SM4#x-oss-server-side-encryption-key-id:7bd6e2fe-cd0e-483e-acb0-f4b9e1******

For more information about server-side encryption, see Server-side encryption.

Upload and generate snapshots

With --snapshot-path, ossutil records the lastModifiedTime of uploaded files and uses it to skip unchanged files in subsequent uploads, accelerating incremental batch uploads. Ensure no other users modify the corresponding objects between uploads. --snapshot-path is best suited for large batch uploads. Example:

ossutil cp -r localfolder/ oss://examplebucket/desfolder/ --snapshot-path=path

Important

ossutil does not auto-delete snapshots in the snapshot-path folder. Periodically remove unneeded snapshots from the snapshot-path folder.
Snapshot I/O adds overhead. For small batches, good network conditions, or shared objects, use --update instead for incremental uploads.
You can use the --update and --snapshot-path options at the same time. ossutil first checks the snapshot-path information to determine whether to skip a file. If the file is not skipped based on the snapshot, ossutil then uses the --update option to determine whether to skip the file.

Upload and configure pay-by-requester

ossutil cp localfolder/examplefile.txt oss://examplebucket/ --payer=requester

Cross-account or cross-region uploads

Use the -e, -i, and -k common options to upload a local file to a bucket in a different region or under a different Alibaba Cloud account.

Note

Specify the endpoint that corresponds to the bucket's region. For more information, see Regions and Endpoints.

ossutil cp exampleobject.txt oss://examplebucket/desfolder/ -e oss-cn-shanghai.aliyuncs.com -i yourAccessKeyID  -k yourAccessKeySecret