The cp command transfers files or directories between your local system and Object Storage Service (OSS), or within OSS. It supports upload, download, and copy operations, with built-in concurrent transfers and Resumable Transfer for large files.
Before using the cp command, ensure that you have installed and configured ossutil.
Usage note
Before performing an upload, download, or copy, ensure the RAM user or RAM role associated with your access credentials has the required permissions for the target bucket and objects. For details, see Grant custom policy permissions to RAM users.
How it works
The ossutil cp command automatically determines whether to upload, download, or copy based on the source and destination path types.
ossutil selects a transfer method based on file size:
Files below the resumable transfer threshold are transferred in a single operation. The default threshold is 100 MB. Change it with the
--bigfile-thresholdoption.Files at or above the threshold use Resumable Transfer. If a transfer is interrupted due to a network error or process termination, ossutil saves the progress and resumes from where it stopped when you rerun the same command. If the transfer cannot be resumed, the incomplete parts remain in the bucket and continue to incur storage charges. Delete parts manually or configure lifecycle rules to delete them automatically.
When Resumable Transfer fails, ossutil creates a .ossutil_checkpoint directory to store checkpoint information. This directory is deleted automatically when the transfer completes. Use the --checkpoint-dir option to specify a different directory for checkpoint records.
Upload objects
Use the cp (upload objects) command to upload local files, images, videos, and other resources to a bucket.
Upload a single object: Upload a file from a local path to a bucket.
Upload in bulk: Upload an entire directory, including all subdirectories and files.
Filter by pattern: Use the
--includeand--excludeoptions to control which files are uploaded. For example, upload only.logfiles or skip all temporary (.tmp) files.
Download objects
Use the cp (download objects) command to download objects from OSS to your local system. Supported operations include bulk downloads, download speed limits, and downloading a specific version from a versioning-enabled bucket.
Download a single object: Download a specified object to a local path.
Download in bulk: Download an entire directory structure from a bucket to your local system.
Download a specific version: If versioning is enabled for your bucket, download a specific historical version of an object.
Copy objects
Use the cp (copy objects) command to copy an object to another bucket in the same region, or to a different path within the same bucket. The copy operation does not modify the object's content.
Cross-bucket copy: Copy an object from one bucket to another within the same region.
In-bucket copy (move or rename): Copy an object from one path to another within the same bucket. To simulate a move or rename, copy the object to the new path and then delete the source.
The ossutil cp command cannot copy objects across regions. To replicate objects between buckets in different regions, use Cross-Region Replication (CRR).
Apply in production
Tune concurrent performance
Adjust the -j, --jobs and --parallel options if the default concurrency does not meet your throughput requirements. By default, ossutil calculates --parallel based on file size. For bulk transfers of large files, effective concurrency equals the number of jobs multiplied by the parallel count.
If the server or Elastic Compute Service (ECS) instance running ossutil has limited resources—such as network bandwidth, memory, or CPU—lower the concurrency values. If resources are underutilized, increase them incrementally.
Setting concurrency too high can degrade performance due to thread-switching overhead and resource contention, and may trigger EOF errors. Start with a low value during performance testing and increase gradually until you find the optimal setting for -j, --jobs and --parallel.
Limit transfer rates
Use the --maxupspeed or --maxdownspeed options to cap upload or download bandwidth and prevent ossutil from saturating your network connection.