Copy, rename, and move objects (original) (raw)

Skip to main content

• Technology areas

  • Overview
  • Guides
  • Reference
  • Samples
  • Resources

• Cross-product tools

• Console

• Discover

• Product overview

• Storage Intelligence overview

• Get started

• Terraform support for Cloud Storage

• Configure and manage Storage Intelligence

• Create buckets

• Create a bucket

• Domain-named bucket verification

• Access and manage buckets

• List buckets

• Change the default storage class of a bucket

• Move and rename buckets

• Delete buckets

• Upload and download objects

• About objects

• Overview of uploads and downloads

• Access and manage objects

• List objects

• Copy, rename, and move objects

• Change an object's storage class

• Tools to access and manage objects using a directory structure

• Object transcoding

• Delete objects

• Get insights on your stored data

• Analyze stored data with Gemini Cloud Assist

• Cache objects

• About caching

• Control data lifecycles

• Options for controlling data lifecycles

• Make requests

• Consistency in Cloud Storage operations

• Batched requests

• Use long-running operations

• Paginate results

• URI wildcards

• Secure data

• Access control

  • Overview
  • Bucket IP filtering
    * Overview
    * Create a bucket with IP filtering rules
    * Create or update IP filtering rules on an existing bucket
    * Get IP bucket filtering rules
    * List bucket IP filtering rules
    * Delete bucket IP filtering rules
    * Disable bucket IP filtering
    * Bypass bucket IP filtering rules
  • Sharing and collaboration scenarios
  • Access control best practices

• Monitor data and usage

• Use Cloud Audit Logs with Cloud Storage

• Usage logs and storage logs

• Use Cloud Audit Logs with storage batch operations

• Use Cloud Logs with storage batch operations

• Use Cloud Audit Logs with Storage Insights

• Use gRPC client-side metrics

• Use client-side traces

• Protection, backup, and recovery

• Overview

• Soft delete

  • Overview
  • Set and manage soft delete policies
  • Use soft-deleted objects
  • Use soft-deleted buckets
  • Set a default soft delete retention duration
  • Use soft delete recommendations
  • Disable soft delete

• Mount buckets with Cloud Storage FUSE

• Overview

• Quickstart

• Install Cloud Storage FUSE

• Mount buckets

• Performance

  • Performance tuning best practices
  • Profile-based configurations for AI/ML workloads
  • Automated configuration values for high-performance machine types
  • Use pre-configured GKE YAML files to optimize Cloud Storage FUSE performance

• Work across products, Clouds, and platforms

• Best practices for media workloads

• Interoperability

• Use Cloud Storage with Big Data

• Integration with Google Cloud Platform services and tools

• Troubleshoot

• Troubleshooting common issues

• Troubleshooting Storage Insights issues

• Troubleshooting Cloud Storage FUSE issues

Copy, rename, and move objects

This page shows you how to copy, rename, and move objects. While some tools perform atomic object move operations, other tools simulate an object move operation by copying the object to a new specified location and then deleting the original object.

• For instructions on copying objects, see Copy objects.
• For instructions on moving or renaming objects by copying them, seeMove or rename objects by copying.
• For instructions on renaming objects atomically, seeRename objects atomically.

We recommend using Storage Transfer Service to move more than 1 TB of data between buckets.

Before you begin

In order to copy, rename, or move objects, you must get the required IAM roles. The following sections describe IAM requirements for different use cases.

Copy objects (including moving or renaming by copying)

To get the permissions that you need to copy objects, ask your administrator to grant you the following IAM roles on the source bucket that contains the objects you want to move, or the destination bucket where you want to move the objects to:

• Storage Object Viewer (roles/storage.objectViewer) on the source bucket
• Storage Object User (roles/storage.objectUser) on the destination bucket
• To copy objects using the Google Cloud console: Viewer basic role (roles/viewer) on both the source bucket and destination bucket, in addition to roles/storage.objectViewer and roles/storage.objectUser

These predefined roles contain the permissions required to copy objects. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to copy objects:

• storage.objects.get on the source bucket
• storage.objects.create on the destination bucket
• storage.objects.delete (required only if you're replacing or overwriting an object in the destination bucket as part of an object copy or move operation) on the destination bucket
• storage.objects.delete (required only if you're moving an object using an underlying copy and delete operation) on the source bucket
• storage.folders.create (required only if the object you're moving is located in a folder that you want to create in the destination bucket) on the destination bucket
• storage.objects.list (required only if you're copying, moving, or renaming an object using the Google Cloud console) on the source and destination buckets
• storage.buckets.list (required only if you're copying, moving, or renaming an object using the Google Cloud console) on the project that contains the source and destination buckets

You can also get these permissions with custom roles.

For information about granting roles on buckets, seeSet and manage IAM policies on buckets. For information about granting roles on projects, see Manage access to projects.

If the object you want to copy has certain features enabled, you might need additional or alternative roles. For example, if the object you want to copy has an object retention configuration you want to retain, you'll need a role on the destination bucket that includes the storage.objects.setRetentionpermission, such as the Storage Object Admin (roles/storage.objectAdmin) role. For more information, seeIAM permissions for Cloud Storage.

Rename objects atomically

To get the permissions that you need to rename objects atomically, ask your administrator to grant you theStorage Object User (roles/storage.objectUser) IAM role on the bucket that contains the object you want to rename.

This predefined role contains the permissions required to rename objects atomically. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to rename objects atomically:

• storage.objects.move
• storage.objects.create
• storage.objects.delete (required only if you're overwriting or replacing an object)

You can also get these permissions with custom roles.

For information about granting roles on buckets, seeSet and manage IAM policies on buckets.

This section describes how to copy objects. You can copy objects from one bucket to another.

Console

1. In the Google Cloud console, go to the Cloud Storage Buckets page.
   Go to Buckets
2. In the list of buckets, click the name of the bucket that contains the object you want to copy.
   The Bucket details page opens, with the Objects tab selected.
3. Navigate to the object, which may be located in a folder.
4. Click the Object overflow menu () associated with the object.
5. Click Copy.
   The Copy object pane appears.
6. In the Destination field, type the name of the destination bucket and the name for the copied object.
   You can alternatively click Browse to select your destination, but browse options are limited to buckets in the current project.
7. Click Copy.

To learn how to get detailed error information about failed Cloud Storage operations in the Google Cloud console, seeTroubleshooting.

Command line

Use the gcloud storage cp command:

gcloud storage cp gs://SOURCE_BUCKET_NAME/SOURCE_OBJECT_NAME gs://DESTINATION_BUCKET_NAME/NAME_OF_COPY

Where:

• SOURCE_BUCKET_NAME is the name of the bucket containing the object you want to copy. For example, my-bucket.
• SOURCE_OBJECT_NAME is the name of the object you want to copy. For example, pets/dog.png.
• DESTINATION_BUCKET_NAME is the name of the bucket where you want to copy your object. For example,another-bucket.
• NAME_OF_COPY is the name you want to give the copy of your object. For example, shiba.png.

If successful, the response is similar to the following example:

Copying gs://example-bucket/file.txt to gs://other-bucket/file-copy.txt Completed files 1/1 | 164.3kiB/164.3kiB

Client libraries

C++

For more information, see theCloud Storage C++ API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

C#

For more information, see theCloud Storage C# API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Go

For more information, see theCloud Storage Go API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Java

For more information, see theCloud Storage Java API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Node.js

For more information, see theCloud Storage Node.js API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

PHP

For more information, see theCloud Storage PHP API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Python

For more information, see theCloud Storage Python API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Ruby

For more information, see theCloud Storage Ruby API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

REST APIs

JSON API

1. Have gcloud CLI installed and initialized, which lets you generate an access token for the Authorization header.
2. Use cURL to call the JSON API with aPOST Object request:
   curl -X POST \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Length: 0" \
   "https://storage.googleapis.com/storage/v1/b/SOURCE_BUCKET_NAME/o/SOURCE_OBJECT_NAME/rewriteTo/b/DESTINATION_BUCKET_NAME/o/NAME_OF_COPY"
   Where:
   • SOURCE_BUCKET_NAME is the name of the bucket containing the object you want to copy. For example,my-bucket.
   • SOURCE_OBJECT_NAME is the URL-encoded name of the object you want to copy. For example, pets/dog.png, URL-encoded as pets%2Fdog.png.
   • DESTINATION_BUCKET_NAME is the name of the bucket where you want to copy your object. For example,another-bucket.
   • NAME_OF_COPY is the URL-encoded name you want to give the copy of your object. For example, shiba.png.
     Since the rewrite method copies data in limited-sized chunks, your copy might require multiple requests, especially for large objects.
     For example, the following response to a rewrite request indicates that you need to make additional rewrite requests:
     {
     "kind": "storage#rewriteResponse",
     "totalBytesRewritten": 1048576,
     "objectSize": 10000000000,
     "done": false,
     "rewriteToken": TOKEN_VALUE
     }
3. Use the rewriteToken in a subsequent request to continue copying data:
   curl -X POST \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Length: 0" \
   -d '{"rewriteToken": "TOKEN_VALUE"}' \
   "https://storage.googleapis.com/storage/v1/b/SOURCE_BUCKET_NAME/o/SOURCE_OBJECT_NAME/rewriteTo/b/DESTINATION_BUCKET_NAME/o/NAME_OF_COPY"
   Where:
   • TOKEN_VALUE is the rewriteToken value returned in the previous request.
   • All other values match those used in the previous request.
     When the object is fully is copied, the last response has a doneproperty set to true, there is no rewriteToken property, and the metadata of the copy is included in the resource property.
     {
     "kind": "storage#rewriteResponse",
     "totalBytesRewritten": 10000000000,
     "objectSize": 10000000000,
     "done": true,
     "resource": objects Resource
     }

XML API

1. Have gcloud CLI installed and initialized, which lets you generate an access token for the Authorization header.
2. Use cURL to call the XML API with aPUT Object request:
   curl -X PUT \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "x-goog-copy-source: SOURCE_BUCKET_NAME/SOURCE_OBJECT_NAME" \
   "https://storage.googleapis.com/DESTINATION_BUCKET_NAME/NAME_OF_COPY"
   Where:
   • SOURCE_BUCKET_NAME is the name of the bucket containing the object you want to copy. For example,my-bucket.
   • SOURCE_OBJECT_NAME is the name of the object you want to copy. For example, pets/dog.png.
   • DESTINATION_BUCKET_NAME is the name of the bucket where you want to copy your object. For example,another-bucket.
   • NAME_OF_COPY is the URL-encoded name you want to give the copy of your object. For example, shiba.png.

Move or rename objects by copying

This section describes how to move or rename objects by using underlying object copy operations. The tools described in this section perform object moves and renames by copying the original object to another namespace and then deleting the original object.

Console

1. In the Google Cloud console, go to the Cloud Storage Buckets page.
   Go to Buckets
2. In the list of buckets, click the name of the bucket that contains the object you want to move.
   The Bucket details page opens, with the Objects tab selected.
3. Navigate to the object, which may be located in a folder.
4. Click the Object overflow menu () associated with the object.
5. If you want to give the object a new name in the same bucket, clickRename.
   1. In the overlay window that appears, enter a new name for the object.
   2. Click Rename.
6. If you want to move the object to a different bucket, click Move.
   1. In the overlay window that appears, click Browse.
   2. Select the destination for the object you are moving.
   3. Click Select.
   4. Click Move.

To learn how to get detailed error information about failed Cloud Storage operations in the Google Cloud console, seeTroubleshooting.

Command line

Use the gcloud storage mv command:

gcloud storage mv gs://SOURCE_BUCKET_NAME/SOURCE_OBJECT_NAME gs://DESTINATION_BUCKET_NAME/DESTINATION_OBJECT_NAME

Where:

• SOURCE_BUCKET_NAME is the name of the bucket containing the object you want to move or rename. For example,my-bucket.
• SOURCE_OBJECT_NAME is the name of the object you want to move or rename. For example, pets/dog.png.
• DESTINATION_BUCKET_NAME is the name of the bucket you want to move the object to. For example,another-bucket.
• DESTINATION_OBJECT_NAME is the name you want your object to have after the move or rename. For example,shiba.png.

If successful, the response is similar to the following example:

Copying gs://example-bucket/old-file.txt to gs://new-bucket/new-file.txt Removing gs://example-bucket/old-file.txt... Completed files 1/1 | 164.3kiB/164.3kiB

Client libraries

C++

For more information, see theCloud Storage C++ API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

C#

For more information, see theCloud Storage C# API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Go

For more information, see theCloud Storage Go API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Java

For more information, see theCloud Storage Java API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Node.js

For more information, see theCloud Storage Node.js API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

PHP

For more information, see theCloud Storage PHP API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Python

For more information, see theCloud Storage Python API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Ruby

For more information, see theCloud Storage Ruby API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

REST APIs

JSON API

For JSON API instructions on moving or renaming objects by copying, see Copy objects.

XML API

For XML API instructions on moving or renaming objects by copying, see Copy objects.

Rename objects atomically

This section describes how to atomically rename objects within a bucket. To rename an object, you can use the Objects: move method in the Cloud Storage JSON API.

REST APIs

JSON API

1. Have gcloud CLI installed and initialized, which lets you generate an access token for the Authorization header.
2. Use cURL to call the JSON API with aObjects: move request:
   curl -X POST \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Length: 0" \
   "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/SOURCE_OBJECT_NAME/moveTo/o/DESTINATION_OBJECT_NAME"
   Where:
   • BUCKET_NAME is the name of the bucket containing the object you want to rename. For example,my-bucket.
   • SOURCE_OBJECT_NAME is the URL-encoded name of the object you want to rename. For example,pets/dog.png, URL-encoded as pets%2Fdog.png.
   • DESTINATION_OBJECT_NAME is the URL-encoded name you want to use. For example, pets/cat.png, URL-encoded as pets%2Fcat.png.

What's next

• Change the storage class of an object.
• Edit an object's metadata.
• Make objects and buckets publicly accessible.
• Learn more about object naming requirements.
• Learn about using request preconditions to prevent race conditions.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-15 UTC.