Copying an Object to a Bucket

You can copy an object from one of your buckets to another bucket that you own or to the bucket of another user provided you have the appropriate permissions. You can also copy an object from the bucket of another user to one of your buckets. For more information, see Access Control List (ACL) Reference.

You are the owner of the copy of the object, which is independent from the source one. You cannot change the key of the object once it is copied in the bucket. If you copy an object with the same name as another object already contained in the bucket, the object you upload replaces the former object. If the bucket versioning is enabled, this former object is conserved as a previous version. For more information, see Enabling or Disabling Bucket Versioning.

This action also returns an ETag element that you need to create a multipart upload. For more information, see Creating a Multipart Upload.

Copying an Object to a Bucket Using AWS CLI (s3api)

Before you begin: Install and configure AWS CLI and set up your profile. For more information, see Installing and Configuring AWS CLI.

To copy an object to one of your buckets, use the copy-object command following this syntax:

Request sample
$ aws s3api copy-object \
    --profile YOUR_PROFILE \
    --copy-source SOURCE_BUCKET/SOURCE_OBJECT \
    --key OBJECT \
    --bucket DESTINATION_BUCKET \
    --acl private \
    --grant-full-control "id=USER_ID, id=USER_ID" \
    --grant-read "id=USER_ID, id=USER_ID" \
    --grant-read-acp "id=USER_ID, id=USER_ID" \
    --grant-write-acp "id=USER_ID, id=USER_ID" \
    --cache-control "no-cache" \
    --content-disposition "inline" \
    --content-encoding  "gzip" \
    --content-language "en" \
    --content-type "image/png" \
    --copy-source-if-match "\"b4fb2aaa356797d9a28bfc640a973720\"" \
    --copy-source-if-modified-since "2023-01-01T00:00:00Z" \
    --copy-source-if-none-match "\"b4fb2aaa356797d9a28bfc640a973720\"" \
    --copy-source-if-unmodified-since "2023-01-01T00:00:00Z" \
    --expires "2024-01-01T00:00:00Z" \
    --metadata "{\"key1\": \"value1\", \"key2\": \"value2"}\" \
    --metadata-directive "COPY" \
    --tagging "key1=value1&key2=value2" \
    --tagging-directive "REPLACE" \
    --website-redirect-location "/new-page.html" \
    --object-lock-mode "COMPLIANCE" \
    --object-lock-retain-until-date "2025-01-01T00:00:00Z" \
    --endpoint https://oos.eu-west-2.outscale.com

This command contains the following attributes that you need to specify:

  • (optional) profile: The named profile you want to use, created when configuring AWS CLI. For more information, see Installing and Configuring AWS CLI.

  • copy-source: The path to the object you want to copy.

  • key: The key for the new object.

    You can use the same prefix in the keys of several objects in the following format: prefix/key1, prefix/key2, and so on.

    This creates a virtual architecture in your bucket and enables you to retrieve your objects faster when listing them. For more information, see Listing the Objects of a Bucket.

  • bucket: The name of the bucket where you want the object to be copied.

    • When specifying new permissions, all the previous permissions are replaced. Therefore, you need to specify both the existing permissions that you want to keep (including for yourself) and the new permissions that you want to give in a single command.

    • If you are the owner of the bucket, you can lose your own permissions but not the ability to manage the ACL itself.

    For more information about existing permissions, see Getting Information About a Bucket ACL and Getting Information About an Object ACL.

  • (optional) acl: The permissions you grant for your object (private | public-read | public-read-write | authenticated-read | bucket-owner-read | bucket-owner-full-control).

  • (optional) grant-full-control: One or more IDs of users to whom you grant the full-control permission.

  • (optional) grant-read: One or more IDs of users to whom you grant the read permission.

  • (optional) grant-read-acp: One or more IDs of users to whom you grant the read-acp permission.

  • (optional) grant-write-acp: One or more IDs of users to whom you grant the write-acp permission.

  • (optional) cache-control: How you want the object to be handled in terms of caching (max-age | max-stale | min-fresh | no-cache | no-store | no-transform | only-if-cached | stale-if-error).

  • (optional) content-disposition: How you want the object to be displayed when accessed via a browser ("inline" | "attachment" | "attachment; filename="<NAME_OF_DOWNLOADED_FILE>"").

    • inline: When possible, prompts the browser to display the content within the browser window itself. This is useful for images, PDFs, and other media types that browsers can easily render.

    • attachment: Regardless of file type, prompts the browser to download the content instead of displaying it inline. The file is thus saved locally.

    • "attachment; filename="<NAME_OF_DOWNLOADED_FILE>"": Regardless of file type, prompts the browser to download the content instead of displaying it inline. The file is thus saved locally with the specified filename.

  • (optional) content-encoding: The encoding format of the object (gzip | compress | deflate | identity | br).

  • (optional) content-language: The language the content of the object is in, in language code (ISO 639 format).

  • (optional) content-type: The MIME (Multipurpose Internet Mail Extensions) type of the object.

    An inaccurately set or absent content-type attribute can cause objects to be misinterpreted or mishandled by browsers. As a result, you may encounter difficulties accessing or viewing your objects using your preferred browser.

  • (optional) copy-source-if-match: Copies the object only if its ETag matches the ETag you specify for this attribute.

  • (optional) copy-source-if-modified-since: Copies the object only if it has been modified after the date and time you specify in UTC format for this attribute.

  • (optional) copy-source-if-none-match: Copies the object only if its ETag does not match the ETag you specify for this attribute.

  • (optional) copy-source-if-unmodified-since: Copies the object only if it has not been modified since the date and time you specify in UTC format for this attribute.

  • (optional) expires: The date and time, in UTC format, at which you consider the object can no longer be cached, and is considered stale.

  • (optional) metadata: A map of additional metadata entries you can freely specify.

    • key: The name of the metadata.

    • value: The value of the metadata.

  • (optional) metadata-directive: Whether you want the metadata to be copied from the source object or replaced with the metadata provided in the request (COPY or REPLACE).

  • (optional) tagging: The tag set you want to associate to the object, and which must be used in conjunction with the TaggingDirective element. The tag set must be in URL query-format.

  • (optional) tagging-directive: Whether you want the tag set the to be copied from the source object or replaced with the tag-set provided in the request (COPY or REPLACE).

  • (optional) website-redirect-location: If you configured the destination bucket as a website, redirects requests for this object to another object in the same bucket or to an external URL.

  • (optional) object-lock-mode: If Object Lock was enabled on the destination bucket, you can specify its mode. For more information, see Configuring a Default Object Lock on Your Bucket.

  • (optional) object-lock-retain-until-date: If Object Lock was enabled on the destination bucket, you can specify the retention date of the object. For more information, see Configuring a Specific Object Lock on an Object.

  • endpoint: The endpoint corresponding to the Region you want to send the request to.

The copy-object command returns the following elements:

  • VersionId: The ID of the version of the copied object.

  • CopyObjectResult: Information about the copy. This element contains the following information about the copy:

    • LastModified: The date and time, in UTC format, at which the object was copied.

    • ETag: The ETag of your object, that you need to use the multipart upload commands. For more information, see Creating a Multipart Upload.

Result Sample
{
    "VersionId": "aJf9Af6Xzf0H00000000001I4j3QKItW",
    "CopyObjectResult": {
        "LastModified": "2017-01-05T13:28:34.676Z",
        "ETag": "fae4684b3d9544fababdd01e9a620584"
    }
}

Copying an Object to a Bucket Using AWS CLI (s3)

Before you begin: Install and configure AWS CLI and set up your profile. For more information, see Installing and Configuring AWS CLI.

To copy an object to one of your buckets, use the cp command following this syntax:

If you want to move the object instead of copying it, replace the cp command with mv.

$ aws s3 cp s3://SOURCE_BUCKET/SOURCE_OBJECT s3://DESTINATION_BUCKET/DESTINATION_OBJECT \
    --profile YOUR_PROFILE \
    --debug \
    --dryrun \
    --acl public-read \
    --cache-control "no-cache" \
    --content-disposition "inline" \
    --content-encoding "gzip" \
    --content-language "en" \
    --content-type image/png \
    --expires "2024-03-01T00:00:00Z" \
    --metadata '{"key1": "value1", "key2": "value2"}' \
    --copy-props none \
    --expected-size 1234 \
    --website-redirect "/new-page.html" \
    --endpoint https://oos.eu-west-2.outscale.com

This command contains the following attributes that you need to specify:

  • s3://SOURCE_BUCKET/SOURCE_OBJECT: The path to the object you want to copy.

  • s3://DESTINATION_BUCKET: The name of the bucket where you want the object to be copied.

  • (optional)/DESTINATION_OBJECT: The name for the copied object, if you want to give it a different name than the source object.

  • (optional) profile: The named profile you want to use, created when configuring AWS CLI. For more information, see Installing and Configuring AWS CLI.

  • (optional) debug: When included, returns a detailed log of the operation. This is useful to analyze and troubleshoot issues you may be encountering.

  • (optional) dryrun: Provides an overview of the operations performed by the command without actually running it. You can use this as a safety measure to review the impact of a command before executing it.

  • (optional) acl: The permissions for the copy of the object (private | public-read | public-read-write | authenticated-read | bucket-owner-read | bucket-owner-full-control).

  • (optional) cache-control: How you want the copy of the object to be handled in terms of caching (max-age | max-stale | min-fresh | no-cache | no-store | no-transform | only-if-cached | stale-if-error).

  • (optional) content-disposition: How you want the object to be displayed when accessed via a browser (inline | attachment | attachment; filename="<NAME_OF_DOWNLOADED_FILE>").

    • inline: When possible, prompts the browser to display the content within the browser window itself. This is useful for images, PDFs, and other media types that browsers can easily render.

    • attachment: Regardless of file type, prompts the browser to download the content instead of displaying it inline. The file is thus saved locally.

    • attachment; filename="<NAME_OF_DOWNLOADED_FILE>": Regardless of file type, prompts the browser to download the content instead of displaying it inline. The file is thus saved locally with the specified filename.

  • (optional) content-encoding: The encoding format of the copy of the object (gzip | compress | deflate | identity | br).

  • (optional) content-language: The language the content of the copy of the object is in, in language code (ISO 639 format).

  • (optional) content-type: The MIME (Multipurpose Internet Mail Extensions) type of the copy of the object.

    An inaccurately set or absent content-type attribute can cause objects to be misinterpreted or mishandled by browsers. As a result, you may encounter difficulties accessing or viewing your objects using your preferred browser.

  • (optional) expires: The date and time, in UTC format, at which you consider the copy of the object can no longer be cached, and is considered stale.

  • (optional) metadata: A map of additional metadata entries you can freely specify.

    • key: The name of the metadata.

    • value: The value of the metadata.

  • (optional) copy-props: Determines the properties you want copied from the source object (none | metadata-directive | default).

    • none refrains from copying any of the properties from the source object.

    • metadata-directive copies the following values from the source object: content-type, content-language, content-encoding, content-disposition, cache-control, expires, and metadata.

    • default-value copies tags and metadata specified by the metadata-directive value from source object.

  • (optional) expected-size: If the object is larger than 50GB, specifies the expected size of the upload, in bytes. This is useful if you want to confirm the integrity or the expected size of the file being downloaded. For more information, see Tutorial: Using Multipart Upload With AWS CLI (s3).

  • (optional) website-redirect: If you configured the bucket as a website, redirects requests for this object to another object in the same bucket or to an external URL.

  • endpoint: The endpoint corresponding to the Region you want to send the request to.

Copying an Object to a Bucket Using s3cmd

You can manage your object storage resources using s3cmd commands. For more information, see s3cmd.

Related Pages

AWS™ and Amazon Web Services™ are trademarks of Amazon Technologies, Inc or its affiliates in the United States and/or other countries.