[Yandex Cloud documentation](../../../index.md) > [Yandex Object Storage](../../index.md) > [Step-by-step guides](../index.md) > Objects > Copying objects

# Copying objects

Object Storage supports server-side copy.

If [bucket](../../concepts/bucket.md) [encryption](../../concepts/encryption.md) is disabled, [objects](../../concepts/object.md) will be copied to server-side buckets. The host running the copy command and Object Storage only exchange object [keys](../../concepts/object.md#key). No fee is charged for the copying traffic in this case because the traffic is internal for the object storage. However, you will be [billed](../../pricing.md#prices-operations) for copy requests.

If bucket objects are encrypted, they will first be copied to the host running the command and then uploaded to the target bucket.

Large objects uploaded using [multipart uploads](../../concepts/multipart.md) are stored in parts within the bucket. To copy these objects, you need to use the [copyPart](../../s3/api-ref/multipart/copypart.md) call for each part. Therefore, multipart objects cost more to copy than regular ones.

You can copy either the [entire bucket contents](#copy-from-bucket-to-bucket) or an [individual bucket object](#copy-single-object).


To work with objects in an [encrypted](../../concepts/encryption.md) bucket, a user or [service account](../../../iam/concepts/users/service-accounts.md) must have the following [roles for the encryption key](../../../kms/operations/key-access.md) in addition to the `storage.configurer` [role](../../security/index.md#storage-configurer):

* `kms.keys.encrypter`: To read the key, [encrypt](../../../kms/security/index.md#kms-keys-encrypter) and upload objects.
* `kms.keys.decrypter`: To read the key, [decrypt](../../../kms/security/index.md#kms-keys-decrypter) and download objects.
* `kms.keys.encrypterDecrypter`: This role includes the `kms.keys.encrypter` and `kms.keys.decrypter` [permissions](../../../kms/security/index.md#kms-keys-encrypterDecrypter).

For more information, see [Key Management Service service roles](../../../kms/security/index.md#service-roles).


## Copying a single object {#copy-single-object}

{% list tabs group=instructions %}

- Yandex Cloud CLI {#cli}

  If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../../cli/quickstart.md#install).

  The folder used by default is the one specified when [creating](../../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

  1. See the description of the CLI command to copy an object:

      ```bash
      yc storage s3api copy-object --help
      ```

  1. Get a list of buckets in the default folder:
     
     ```bash
     yc storage bucket list
     ```
     
     Result:
     
     ```text
     +------------------+----------------------+-------------+-----------------------+---------------------+
     |       NAME       |      FOLDER ID       |  MAX SIZE   | DEFAULT STORAGE CLASS |     CREATED AT      |
     +------------------+----------------------+-------------+-----------------------+---------------------+
     | first-bucket     | b1gmit33ngp6******** | 53687091200 | STANDARD              | 2022-12-16 13:58:18 |
     +------------------+----------------------+-------------+-----------------------+---------------------+
     ```
  1. Run this command:

      ```bash
      yc storage s3api copy-object \
        --copy-source <source_bucket>/<object_key> \
        --bucket <target_bucket> \
        --key <object_key>
      ```

      Where:

      * `--copy-source`: Name of the source bucket and object [key](../../concepts/object.md#key) you need to copy.
      * `--bucket`: Name of the bucket to copy the object to.
      * `--key`: Key by which to store the object in the bucket.

      Result:

      ```bash
      copy_object_result:
        etag: '"d41d8cd98f00b204e9800998********"'
        last_modified_at: "2024-10-08T14:21:41.628Z"
      request_id: 61523025********
      copy_source_version_id: "null"
      ```

      Alternative command:

      ```bash
      yc storage s3 cp \
        s3://<source_bucket>/<original_object_key> \
        s3://<target_bucket>/<copy_object_key>
      ```

      Result:

      ```text
      copy: s3://my-bucket/object.txt to s3://new-bucket/object-copy.txt
      ```

      Learn more about the command configuration [here](#yc-s3-cp-config).

- AWS CLI {#aws-cli}

  1. If you do not have the AWS CLI yet, [install and configure it](../../tools/aws-cli.md).
  1. Run this command:

      ```bash
      aws --endpoint-url=https://storage.yandexcloud.net/ \
        s3 cp s3://<source_bucket>/<object_key> s3://<target_bucket>/<object_key>
      ```

      Where:

      * `--endpoint-url`: Object Storage endpoint.
      * `s3 cp`: Copy object command.

      Result:

      ```text
      copy: s3://<source_bucket>/<object_key> to s3://<target_bucket>/<object_key>
      ```

      For more information about the `aws s3 cp` command, see [AWS CLI Command Reference](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3/cp.html).

{% endlist %}

## Copying multiple objects to another bucket {#copy-from-bucket-to-bucket}

{% list tabs group=instructions %}

- Yandex Cloud CLI {#cli}

  If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../../cli/quickstart.md#install).

  The folder used by default is the one specified when [creating](../../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

  1. See the description of the CLI command to copy objects:

      ```bash
      yc storage s3 cp --help
      ```

  1. Get a list of buckets in the default folder:
     
     ```bash
     yc storage bucket list
     ```
     
     Result:
     
     ```text
     +------------------+----------------------+-------------+-----------------------+---------------------+
     |       NAME       |      FOLDER ID       |  MAX SIZE   | DEFAULT STORAGE CLASS |     CREATED AT      |
     +------------------+----------------------+-------------+-----------------------+---------------------+
     | first-bucket     | b1gmit33ngp6******** | 53687091200 | STANDARD              | 2022-12-16 13:58:18 |
     +------------------+----------------------+-------------+-----------------------+---------------------+
     ```
  1. Run this command:

      ```bash
      yc storage s3 cp \
        s3://<source_bucket>/ \
        s3://<target_bucket>/ \
        --recursive \
        --exclude "*" \
        --include "*.txt"
      ```

      Where:
      * `--recursive`: Copies all objects.
      * `--exclude`: Excludes objects that match the pattern from copying. In the example, it excludes all objects (`"*"`). This is an optional setting.
      * `--include`: Adds objects that match the pattern to copying. In the example, it adds only `.txt` files. This is an optional setting.

      The `--exclude` and `--include` parameters are applied in the order they are specified. To only copy objects matching a pattern, first exclude all objects using `--exclude "*"`, then include the required ones using `--include`. To exclude objects with a specific prefix, use only `--exclude`, e.g., `--exclude "prefix/*"`.

      Result:

      ```text
      copy: s3://my-bucket/object-1.txt to s3://new-bucket/object-1-copy.txt
      copy: s3://my-bucket/object-2.txt to s3://new-bucket/object-2-copy.txt
      ...
      copy: s3://my-bucket/object-n.txt to s3://new-bucket/object-n-copy.txt
      ```

      Learn more about the command configuration [here](#yc-s3-cp-config).

- AWS CLI {#aws-cli}

  1. If you do not have the AWS CLI yet, [install and configure it](../../tools/aws-cli.md).
  1. Run this command:

      ```bash
      aws --endpoint-url=https://storage.yandexcloud.net/ \
        s3 cp --recursive \
        --exclude "*" \
        --include "*.txt" \
        s3:<source_bucket>/ s3:<target_bucket>/
      ```

      Where:

      * `--endpoint-url`: Object Storage endpoint.
      * `s3 cp`: Command to copy objects.
      * `--recursive`: Copies all objects.
      * `--exclude`: Excludes objects that match the pattern from copying. In the example, it excludes all objects (`"*"`). This is an optional setting.
      * `--include`: Adds objects that match the pattern to copying. In the example, it adds only `.txt` files. This is an optional setting.

      The `--exclude` and `--include` parameters are applied in the order they are specified. To only copy objects matching a pattern, first exclude all objects using `--exclude "*"`, then include the required ones using `--include`. To exclude objects with a specific prefix, use only `--exclude`, e.g., `--exclude "prefix/*"`.

      For more information about the `aws s3 cp` command, see [AWS CLI Command Reference](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3/cp.html).

  {% note info %}

  You can copy objects between buckets, both within the same cloud and across different clouds. To do this, make sure your [service account](../../../iam/concepts/users/service-accounts.md) has write permissions for both buckets.

  {% endnote %}


{% endlist %}


## Configuring parameters for the yc storage s3 cp command {#yc-s3-cp-config}

{% list tabs group=instructions %}

- Yandex Cloud CLI {#cli}

  You can set the following parameters for the `yc storage s3 cp` command:
  
  * `s3.max-queue-size`: Maximum number of issues per queue. The default value is `1,000`.
  * `s3.max-concurrent-requests`: Maximum number of simultaneous requests. The default value is `10`.
  * `s3.multipart-threshold`: Object threshold size to trigger a multipart upload if exceeded. The default value is `8MB`.
  * `s3.multipart-chunksize`: Size of parts the object will be split into in a multipart upload. The default value is `8MB`.
  
  To set these parameters, use the `yc config set <parameter> <value>` command.

{% endlist %}

## Loading error {#errors}

When loading large files using the Yandex Cloud CLI, you may get this error: `fatal error: runtime: out of memory`. The amount of memory required to load large files is calculated with this formula:

```text
s3.max-concurrent-requests × s3.multipart-chunksize
```

Where:

* `s3.max-concurrent-requests`: Maximum number of simultaneous requests. The default value is `10`.
* `s3.multipart-chunksize`: Size of parts the object will be split into in a multipart upload. The default value is `8 MB`.

Learn more about the command configuration [here](#yc-s3-cp-config).