copy-object

Available in Classic and VPC

Copy and save an object stored in a Ncloud Storage bucket. You can copy objects up to 5 GB in size, and copying is only allowed between buckets in the same Region.

Note

For a Sub Account user to execute this command, they must have View/GetObject permissions (for the bucket containing the object to be copied) and Change/PutObject permissions (for the destination bucket where the object will be stored).

Syntax

The copy-object syntax is as follows:

aws s3api copy-object \
    --bucket <bucket> \
    --copy-source <copy-source> \
    --key <key> \
    [--cache-control <cache-control>] \
    [--content-disposition <content-disposition>] \
    [--content-encoding <content-encoding>] \
    [--content-language <content-language>] \
    [--content-type <content-type>] \
    [--metadata <metadata>] \
    [--metadata-directive <metadata-directive>] \
    [--storage-class <storage-class>] \
    [--server-side-encryption <server-side-encryption>] \
    [--sse-customer-algorithm <sse-customer-algorithm>] \
    [--sse-customer-key <sse-customer-key>] \
    [--sse-customer-key-md5 <sse-customer-key-md5>] \
    [--copy-source-sse-customer-algorithm <copy-source-sse-customer-algorithm>] \
    [--copy-source-sse-customer-key <copy-source-sse-customer-key>] \
    [--copy-source-sse-customer-key-md5 <copy-source-sse-customer-key-md5>] \
    [--object-lock-mode <object-lock-mode>] \
    [--object-lock-retain-until-date <object-lock-retain-until-date>] \
    [--object-lock-legal-hold-status <object-lock-legal-hold-status>] \
    --endpoint-url <endpoint-url>

Note

You can copy objects up to 5 GB in size with a single copy operation. To copy an object larger than 5 GB, use upload-part-copy.

Options

This section describes the options available when running copy-object.

Required options

The following options are required for copy-object.

Options	Type	Required	Description
`--bucket`	String	Required	Bucket name
`--copy-source`	String	Required	Source object to copy Enter in the `{bucket_name}/{object_name}` format (e.g., `my-test-bucket/img/image.png`). Bucket name: See list-buckets. Object name: See list-objects-v2. When copying a specific version of an object from a bucket with versioning enabled, add `?versionId={versionId}` to the input. Check version ID: See list-object-versions. Up to 5 GB.
`--key`	String	Required	Object name

Optional options

These are the optional options for copy-object. Options that are not specified will use their default values.

Options	Type	Required	Description
`--cache-control`	String	Optional	Caching behavior
`--content-disposition`	String	Optional	Display format of requested data
`--content-encoding`	String	Optional	Encoding format of requested data
`--content-language`	String	Optional	Request data language
`--content-type`	String	Optional	Request data format.
`--metadata`	String	Optional	Metadata to be stored with the object
`--metadata-directive`	String	Optional	Metadata processing method `COPY` (default) \| `REPLACE` `COPY`: Copy original. `REPLACE`: Redefine.
`--storage-class`	String	Optional	Storage class `STANDARD` (default) \| `ONEZONE_IA` \| `DEEP_ARCHIVE` `STANDARD`: Standard Class `ONEZONE_IA`: One Zone-IA (Infrequent Access) Class `DEEP_ARCHIVE`: Archive Class
`--server-side-encryption`	String	Optional	Server-side encryption method `AES256` \| `aws:kms` `AES256`: SSE-S3 (server management key) `aws:kms`: SSE-KMS (KMS management key)
`--sse-customer-algorithm`	String	Optional	User encryption algorithm (AES256)
`--sse-customer-key`	String	Optional	User-provided encryption key
`--sse-customer-key-md5`	String	Optional	User-provided encryption key's MD5 value
`--copy-source-sse-customer-algorithm`	String	Optional	User encryption algorithm (AES256) of the source
`--copy-source-sse-customer-key`	String	Optional	User-provided encryption key of the source
`--copy-source-sse-customer-key-md5`	String	Optional	MD5 value of the source user-provided encryption key
`--object-lock-mode`	String	Optional	Object retention mode `GOVERNANCE` \| `COMPLIANCE` `GOVERNANCE`: Can be bypassed with special permissions. `COMPLIANCE`: No one can bypass it. Specify with `--object-lock-retain-until-date`. Available only in buckets with object lock enabled.
`--object-lock-retain-until-date`	String	Optional	Object retention expiration date ISO 8601 format. Specify with `--object-lock-mode`. Available only in buckets with object lock enabled.
`--object-lock-legal-hold-status`	String	Optional	Legal hold status `ON` \| `OFF` Available only in buckets with object lock enabled

Common options

For information about the options common to all aws subcommands, see Ncloud Storage options.

Examples

If the object copy request is successful, the copy's identification information and the original version information are returned.

Command

The following is an example command for copying an object from a bucket with versioning enabled.

aws s3api copy-object --bucket my-test-bucket \
    --key img/copy.png \
    --copy-source my-test-bucket/img/image.png \
    --endpoint-url=https://kr.ncloudstorage.com

Output

The following is an example output for copying an object from a bucket with versioning enabled.

{
    "CopySourceVersionId": "11111111-2222-3333-4444-555555555551",
    "VersionId": "11111111-2222-3333-4444-555555555553",
    "ServerSideEncryption": "AES256",
    "CopyObjectResult": {
        "ETag": "\"7cb4883d8f0eede455af0738a2d83b4b\"",
        "LastModified": "2026-09-04T06:32:35Z",
        "ChecksumType": "FULL_OBJECT",
        "ChecksumCRC32": "35sEXg=="
    }
}

Related commands

Related commands are as follows: