Copy objects within a bucket or between buckets in the same region using the ossutil cp command. The object content remains unchanged.
Prerequisites
Before you begin, make sure you have the following permissions on the source and destination buckets:
oss:GetObjectoss:ListObjectsoss:PutObject
For details, see Grant custom access policies to RAM users.
Usage notes
Only objects can be copied. Unmerged parts from an incomplete multipart upload cannot be copied.
By default, both object metadata and tags are copied. Use
--copy-propsto change this behavior.Cross-account and cross-region copy operations are not supported. To migrate objects across accounts or regions, use ossimport or Data Online Migration.
The
-u/--updateoption sends at least one HEAD request per object, regardless of whether the destination object exists. In scenarios with infrequent data changes, this generates unnecessary requests that may affect performance and incur additional request fees. Evaluate your use case carefully before using this option.
Command format
ossutil cp oss://src_bucket[/src_prefix] oss://dest_bucket[/dest_prefix] [flags]Path parameters
| Parameter | Type | Description |
|---|---|---|
src_bucket | string | The name of the source bucket. |
src_prefix | string | A directory or prefix in the source bucket. |
dest_bucket | string | The name of the destination bucket. |
dest_prefix | string | A directory or prefix in the destination bucket. |
Destination object naming rules
The destination object name depends on dest_prefix and whether you are copying a single object or in batch:
| Scenario | dest_prefix | Destination object name |
|---|---|---|
| Single object copy | Empty | Relative path of the source object |
| Single object copy | Ends with / | dest_prefix + relative path of the source object |
| Single object copy | Does not end with / | Identical to dest_prefix |
| Batch copy | Ends with / | dest_prefix + relative path of the source object |
| Batch copy | Does not end with / | dest_prefix + / + relative path of the source object |
Options
For a full list of global options, see Command-line options.
Copy behavior
| Option | Type | Description |
|---|---|---|
-r, --recursive | / | Apply the command recursively to all matching objects in the bucket. Without this option, the command applies only to the object specified by the path. |
-f, --force | / | Skip the confirmation prompt. |
--copy-props | string | Control how object attributes and tags are copied. Valid values: default (copy both attributes and tags), metadata (copy attributes only), none (copy data only, skip attributes and tags). Default: default. Attributes include Content-Type, Content-Language, Content-Encoding, Content-Disposition, Cache-Control, Expires, and user metadata. |
--acl | string | Set the access control list (ACL) of the destination object. Valid values: private, public-read, public-read-write, Default (inherit from bucket). |
--storage-class | string | Set the storage class of the destination object. Valid values: Standard, IA (Infrequent Access), Archive, ColdArchive (Cold Archive), DeepColdArchive (Deep Cold Archive). |
--metadata | strings | Set user metadata on the destination object. Use key=value format. |
--metadata-directive | string | Control how to set the destination object's metadata. Valid values: COPY, REPLACE. |
--tagging | string | Set tags on the destination object. Use key=value format. |
--tagging-directive | string | Control how to set the destination object's tags. Valid values: COPY, REPLACE. |
--version-id | string | The version ID of the source object to copy. |
--request-payer | string | The payment method for the request. For pay-by-requester buckets, set this to requester. |
Incremental copy
| Option | Type | Description |
|---|---|---|
-u, --update | / | Skip destination objects that already exist and were modified more recently than the corresponding source objects. If the destination object has the same modification time as the source object, the destination object is updated. |
--checksum | / | Copy only source objects whose size or CRC64 checksum (if it exists) differs from the destination object. Valid for object-to-object copy only. The check sequence is: (1) compare sizes; (2) if sizes match, compare CRC64 checksums; (3) copy only if checksums differ. |
--size-only | / | Copy only source objects whose size differs from the destination object. |
--ignore-existing | / | Skip destination objects that already exist. Only objects not present at the destination are transferred. |
Filtering
| Option | Type | Description |
|---|---|---|
--include | stringArray | Rules to include objects by path or filename pattern. |
--include-from | stringArray | Read inclusion rules from a file. |
--exclude | stringArray | Rules to exclude objects by path or filename pattern. |
--exclude-from | stringArray | Read exclusion rules from a file. |
--filter | stringArray | Rules to filter objects by path or filename. |
--filter-from | stringArray | Read filtering rules from a file. |
--min-age | Duration | Copy only objects modified before the specified time interval. Default unit: seconds. Example: 1h copies only objects modified 1 hour ago or earlier. |
--max-age | Duration | Copy only objects modified within the specified time interval. Default unit: seconds. Example: 1h copies only objects modified within the last hour. |
--min-mtime | Time | Copy only objects modified after the specified UTC time. Format: 2006-01-02T15:04:05. |
--max-mtime | Time | Copy only objects modified before the specified UTC time. Format: 2006-01-02T15:04:05. |
--min-size | SizeSuffix | The minimum size of an object to transfer. Default unit: bytes. Supported suffixes: B, K, M, G, T, P. 1 K (KiB) = 1024 B. |
--max-size | SizeSuffix | The maximum size of an object to transfer. Default unit: bytes. Supported suffixes: B, K, M, G, T, P. 1 K (KiB) = 1024 B. |
--start-after | string | Copy only objects that are alphabetically after the specified value. |
--end-with | string | Copy only objects that are alphabetically before or equal to the specified value. |
--metadata-include | stringArray | Rules to include object metadata. |
--metadata-exclude | stringArray | Rules to exclude object metadata. |
--metadata-filter | stringArray | Rules to filter object metadata. |
--metadata-filter-from | stringArray | Read object metadata filtering rules from a file. |
-d, --dirs | string | Process objects and subdirectories in the current directory without recursing into subdirectories. |
--list-objects | / | Use the ListObjects operation to list objects. |
--encoding-type | string | Encoding type for input object names or filenames. Valid value: url. |
Input from file
| Option | Type | Description |
|---|---|---|
--files-from | stringArray | Read the list of source objects from a file. Empty lines and commented lines are ignored. |
--files-from-raw | stringArray | Read the list of source objects from a file, including empty and commented lines. |
Performance
| Option | Type | Description |
|---|---|---|
-j, --job | int | Number of concurrent tasks. Default: 3. Takes effect only when used with -f, --update, --size-only, or --ignore-existing. |
--parallel | int | Number of concurrent tasks for internal operations within a single object. |
--checkers | int | Number of checkers to run in parallel. Default: 16. |
--bandwidth-limit | SizeSuffix | Limit network bandwidth. Minimum: 1024 B/s. Default unit: B/s. Supported units: B, K, M, G. Example: 50M limits bandwidth to 50 MB/s. |
--bigfile-threshold | SizeSuffix | Size threshold for enabling multipart copy. Default: 104857600 (100 MiB). |
--part-size | SizeSuffix | Part size for multipart copy. ossutil automatically calculates a suitable part size by default. Valid range: 100 KiB–5 GiB. |
--page-size | int | Maximum number of objects listed per page during batch copy. Default: 1000. Valid range: 1–1000. |
HTTP metadata
| Option | Type | Description |
|---|---|---|
--cache-control | string | Caching behavior when the object is downloaded. |
--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 of the cached content. |
Checkpoint and output
| Option | Type | Description |
|---|---|---|
--checkpoint-dir | string | Directory for checkpoint files used in resumable operations. Default: .ossutil_checkpoint/. |
--output-dir | string | Directory for error report files generated during batch processing. Default: ossutil_output. |
--no-progress | / | Suppress the progress bar. |
--no-error-report | / | Suppress error report file generation during batch processing. |
Examples
Copy a single object
Copy examplefile.txt to a folder in the same bucket:
ossutil cp oss://examplebucket1/examplefile.txt oss://examplebucket1/desfolder/Rename an object
Copy an object to a new key in the same bucket:
ossutil cp oss://examplebucket1/examplefile.txt oss://examplebucket1/example.txtcp leaves the source object intact. Delete the source object manually after renaming if needed.Copy incremental objects
Use --update to skip destination objects that already exist and are newer than the source:
ossutil cp oss://examplebucket1/srcfolder1/ oss://examplebucket1/desfolder/ -r --updateCopy objects between buckets after same-region replication
Use --checksum for strict content consistency verification—for example, to retry a failed batch copy while skipping already-copied objects:
ossutil cp oss://examplebucket1/srcfolder1/ oss://examplebucket1/desfolder/ -r --checksumThe command compares sizes first. If sizes match, it compares CRC64 checksums and copies only objects where the checksums differ.
Use --ignore-existing to transfer only objects not yet present at the destination:
ossutil cp oss://examplebucket1/srcfolder1/ oss://examplebucket1/desfolder/ -r --ignore-existingModify object tags
Update the tags on an object by copying it to the same path with new tags:
ossutil cp oss://examplebucket1/examplefile.txt oss://examplebucket1/ --tagging "abc=1&bcd=2&……"