Console
    Contact Us Start free

    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.

    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 permissionssection:

    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, see Use IAM with 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.setRetention permission, such as the Storage Object Admin ( roles/storage.objectAdmin ) role. For more information, see IAM permissions for Cloud Storage .

    Rename objects atomically

    To get the permissions that you need to rename objects atomically, ask your administrator to grant you the Storage 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 permissionssection:

    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, see Use IAM with buckets .

    Copy objects

    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 detailspage opens, with the Objectstab selected.

    3. Navigate to the object, which may be located in a folder.

    4. Click the Object overflowmenu ( ) associated with the object.

    5. Click Copy.

      The Copy objectpane appears.

    6. In the Destinationfield, type the name of the destination bucket and the name for the copied object.

      You can alternatively click Browseto 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, see Troubleshooting .

    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 the Cloud Storage C++ API reference documentation .

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

      namespace 
  
 gcs 
  
 = 
  
 :: 
 google 
 :: 
 cloud 
 :: 
 storage 
 ; 
 using 
  
 :: 
 google 
 :: 
 cloud 
 :: 
 StatusOr 
 ; 
 []( 
 gcs 
 :: 
 Client 
  
 client 
 , 
  
 std 
 :: 
 string 
  
 const 
&  
 source_bucket_name 
 , 
  
 std 
 :: 
 string 
  
 const 
&  
 source_object_name 
 , 
  
 std 
 :: 
 string 
  
 const 
&  
 destination_bucket_name 
 , 
  
 std 
 :: 
 string 
  
 const 
&  
 destination_object_name 
 ) 
  
 { 
  
 StatusOr<gcs 
 :: 
 ObjectMetadata 
>  
 new_copy_meta 
  
 = 
  
 client 
 . 
 CopyObject 
 ( 
 source_bucket_name 
 , 
  
 source_object_name 
 , 
  
 destination_bucket_name 
 , 
  
 destination_object_name 
 ); 
  
 if 
  
 ( 
 ! 
 new_copy_meta 
 ) 
  
 throw 
  
 std 
 :: 
 move 
 ( 
 new_copy_meta 
 ). 
 status 
 (); 
  
 std 
 :: 
 cout 
 << 
 "Successfully copied " 
 << 
 source_object_name 
 << 
 " in bucket " 
 << 
 source_bucket_name 
 << 
 " to bucket " 
 << 
 new_copy_meta 
 - 
> bucket 
 () 
 << 
 " with name " 
 << 
 new_copy_meta 
 - 
> name 
 () 
 << 
 ". 
 \n 
 The full metadata after the copy is: " 
 << 
 * 
 new_copy_meta 
 << 
 " 
 \n 
 " 
 ; 
 }

    C#

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

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

      using 
  
  Google.Cloud.Storage.V1 
 
 ; 
 using 
  
 System 
 ; 
 public 
  
 class 
  
 CopyFileSample 
 { 
  
 public 
  
 void 
  
 CopyFile 
 ( 
  
 string 
  
 sourceBucketName 
  
 = 
  
 "source-bucket-name" 
 , 
  
 string 
  
 sourceObjectName 
  
 = 
  
 "source-file" 
 , 
  
 string 
  
 destBucketName 
  
 = 
  
 "destination-bucket-name" 
 , 
  
 string 
  
 destObjectName 
  
 = 
  
 "destination-file-name" 
 ) 
  
 { 
  
 var 
  
 storage 
  
 = 
  
  StorageClient 
 
 . 
  Create 
 
 (); 
  
 storage 
 . 
 CopyObject 
 ( 
 sourceBucketName 
 , 
  
 sourceObjectName 
 , 
  
 destBucketName 
 , 
  
 destObjectName 
 ); 
  
 Console 
 . 
 WriteLine 
 ( 
 $"Copied {sourceBucketName}/{sourceObjectName} to " 
  
 + 
  
 $"{destBucketName}/{destObjectName}." 
 ); 
  
 } 
 }

    Go

    For more information, see the Cloud Storage Go API reference documentation .

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

      import 
  
 ( 
  
 "context" 
  
 "fmt" 
  
 "io" 
  
 "time" 
  
 "cloud.google.com/go/storage" 
 ) 
 // copyFile copies an object into specified bucket. 
 func 
  
 copyFile 
 ( 
 w 
  
 io 
 . 
  Writer 
 
 , 
  
 dstBucket 
 , 
  
 srcBucket 
 , 
  
 srcObject 
  
 string 
 ) 
  
 error 
  
 { 
  
 // dstBucket := "bucket-1" 
  
 // srcBucket := "bucket-2" 
  
 // srcObject := "object" 
  
 ctx 
  
 := 
  
 context 
 . 
 Background 
 () 
  
 client 
 , 
  
 err 
  
 := 
  
 storage 
 . 
 NewClient 
 ( 
 ctx 
 ) 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "storage.NewClient: %w" 
 , 
  
 err 
 ) 
  
 } 
  
 defer 
  
 client 
 . 
 Close 
 () 
  
 ctx 
 , 
  
 cancel 
  
 := 
  
 context 
 . 
 WithTimeout 
 ( 
 ctx 
 , 
  
 time 
 . 
 Second 
 * 
 10 
 ) 
  
 defer 
  
 cancel 
 () 
  
 dstObject 
  
 := 
  
 srcObject 
  
 + 
  
 "-copy" 
  
 src 
  
 := 
  
 client 
 . 
  Bucket 
 
 ( 
 srcBucket 
 ). 
  Object 
 
 ( 
 srcObject 
 ) 
  
 dst 
  
 := 
  
 client 
 . 
  Bucket 
 
 ( 
 dstBucket 
 ). 
  Object 
 
 ( 
 dstObject 
 ) 
  
 // Optional: set a generation-match precondition to avoid potential race 
  
 // conditions and data corruptions. The request to copy is aborted if the 
  
 // object's generation number does not match your precondition. 
  
 // For a dst object that does not yet exist, set the DoesNotExist precondition. 
  
 dst 
  
 = 
  
 dst 
 . 
 If 
 ( 
 storage 
 . 
  Conditions 
 
 { 
 DoesNotExist 
 : 
  
 true 
 }) 
  
 // If the destination object already exists in your bucket, set instead a 
  
 // generation-match precondition using its generation number. 
  
 // attrs, err := dst.Attrs(ctx) 
  
 // if err != nil { 
  
 // 	return fmt.Errorf("object.Attrs: %w", err) 
  
 // } 
  
 // dst = dst.If(storage.Conditions{GenerationMatch: attrs.Generation}) 
  
 if 
  
 _ 
 , 
  
 err 
  
 := 
  
 dst 
 . 
  CopierFrom 
 
 ( 
 src 
 ). 
 Run 
 ( 
 ctx 
 ); 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "Object(%q).CopierFrom(%q).Run: %w" 
 , 
  
 dstObject 
 , 
  
 srcObject 
 , 
  
 err 
 ) 
  
 } 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "Blob %v in bucket %v copied to blob %v in bucket %v.\n" 
 , 
  
 srcObject 
 , 
  
 srcBucket 
 , 
  
 dstObject 
 , 
  
 dstBucket 
 ) 
  
 return 
  
 nil 
 }

    Java

    For more information, see the Cloud Storage Java API reference documentation .

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

      import 
  
 com.google.cloud.storage. BlobId 
 
 ; 
 import 
  
 com.google.cloud.storage. BlobInfo 
 
 ; 
 import 
  
 com.google.cloud.storage. CopyWriter 
 
 ; 
 import 
  
 com.google.cloud.storage. Storage 
 
 ; 
 import 
  
 com.google.cloud.storage. Storage 
. CopyRequest 
 
 ; 
 import 
  
 com.google.cloud.storage. StorageOptions 
 
 ; 
 public 
  
 class 
 CopyObject 
  
 { 
  
 public 
  
 static 
  
 void 
  
 copyObject 
 ( 
  
 String 
  
 projectId 
 , 
  
 String 
  
 sourceBucketName 
 , 
  
 String 
  
 objectName 
 , 
  
 String 
  
 targetBucketName 
 ) 
  
 throws 
  
 Exception 
  
 { 
  
 // The ID of your GCP project 
  
 // String projectId = "your-project-id"; 
  
 // The ID of the bucket the original object is in 
  
 // String sourceBucketName = "your-source-bucket"; 
  
 // The ID of the GCS object to copy 
  
 // String objectName = "your-object-name"; 
  
 // The ID of the bucket to copy the object to 
  
 // String targetBucketName = "target-object-bucket"; 
  
 try 
  
 ( 
  Storage 
 
  
 storage 
  
 = 
  
  StorageOptions 
 
 . 
 newBuilder 
 (). 
 setProjectId 
 ( 
 projectId 
 ). 
 build 
 (). 
  getService 
 
 ()) 
  
 { 
  
  BlobId 
 
  
 sourceId 
  
 = 
  
  BlobId 
 
 . 
 of 
 ( 
 sourceBucketName 
 , 
  
 objectName 
 ); 
  
 // you could change "objectName" to rename the object 
  
  BlobId 
 
  
 targetId 
  
 = 
  
  BlobId 
 
 . 
 of 
 ( 
 targetBucketName 
 , 
  
 objectName 
 ); 
  
 // Recommended: set a generation-match precondition to avoid potential race 
  
 // conditions and data corruptions. The request returns a 412 error if the 
  
 // preconditions are not met. 
  
  Storage 
 
 . 
 BlobTargetOption 
  
 precondition 
 ; 
  
  BlobInfo 
 
  
 existingTarget 
  
 = 
  
 storage 
 . 
 get 
 ( 
 targetBucketName 
 , 
  
 objectName 
 ); 
  
 if 
  
 ( 
 existingTarget 
  
 == 
  
 null 
 ) 
  
 { 
  
 // For a target object that does not yet exist, set the DoesNotExist precondition. 
  
 // This will cause the request to fail if the object is created before the request runs. 
  
 precondition 
  
 = 
  
  Storage 
 
 . 
 BlobTargetOption 
 . 
 doesNotExist 
 (); 
  
 } 
  
 else 
  
 { 
  
 // If the destination already exists in your bucket, instead set a generation-match 
  
 // precondition. This will cause the request to fail if the existing object's generation 
  
 // changes before the request runs. 
  
 precondition 
  
 = 
  
  Storage 
 
 . 
 BlobTargetOption 
 . 
 generationMatch 
 ( 
 existingTarget 
 . 
  getGeneration 
 
 ()); 
  
 } 
  
  CopyRequest 
 
  
 copyRequest 
  
 = 
  
  CopyRequest 
 
 . 
 newBuilder 
 () 
  
 . 
 setSource 
 ( 
 sourceId 
 ) 
  
 . 
 setTarget 
 ( 
 targetId 
 , 
  
 precondition 
 ) 
  
 // limit the number of bytes Cloud Storage will attempt to copy before responding to 
  
 // an individual request. 
  
 // If you see Read Timeout errors, try reducing this value. 
  
 . 
  setMegabytesCopiedPerChunk 
 
 ( 
 2048L 
 ) 
  
 // 2GiB 
  
 . 
 build 
 (); 
  
  CopyWriter 
 
  
 copyWriter 
  
 = 
  
 storage 
 . 
 copy 
 ( 
 copyRequest 
 ); 
  
  BlobInfo 
 
  
 successfulCopyResult 
  
 = 
  
 copyWriter 
 . 
  getResult 
 
 (); 
  
 System 
 . 
 out 
 . 
 printf 
 ( 
  
 "Copied object gs://%s/%s to %s%n" 
 , 
  
 sourceBucketName 
 , 
  
 objectName 
 , 
  
 successfulCopyResult 
 . 
  getBlobId 
 
 (). 
  toGsUtilUriWithGeneration 
 
 ()); 
  
 } 
  
 } 
 }

    Node.js

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

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

      /** 
 * TODO(developer): Uncomment the following lines before running the sample. 
 */ 
 // The ID of the bucket the original file is in 
 // const srcBucketName = 'your-source-bucket'; 
 // The ID of the GCS file to copy 
 // const srcFilename = 'your-file-name'; 
 // The ID of the bucket to copy the file to 
 // const destBucketName = 'target-file-bucket'; 
 // The ID of the GCS file to create 
 // const destFileName = 'target-file-name'; 
 // Imports the Google Cloud client library 
 const 
  
 { 
 Storage 
 } 
  
 = 
  
 require 
 ( 
 ' @google-cloud/storage 
' 
 ); 
 // Creates a client 
 const 
  
 storage 
  
 = 
  
 new 
  
 Storage 
 (); 
 async 
  
 function 
  
 copyFile 
 () 
  
 { 
  
 const 
  
 copyDestination 
  
 = 
  
 storage 
 . 
 bucket 
 ( 
 destBucketName 
 ). 
 file 
 ( 
 destFileName 
 ); 
  
 // Optional: 
  
 // Set a generation-match precondition to avoid potential race conditions 
  
 // and data corruptions. The request to copy is aborted if the object's 
  
 // generation number does not match your precondition. For a destination 
  
 // object that does not yet exist, set the ifGenerationMatch precondition to 0 
  
 // If the destination object already exists in your bucket, set instead a 
  
 // generation-match precondition using its generation number. 
  
 const 
  
 copyOptions 
  
 = 
  
 { 
  
 preconditionOpts 
 : 
  
 { 
  
 ifGenerationMatch 
 : 
  
 destinationGenerationMatchPrecondition 
 , 
  
 }, 
  
 }; 
  
 // Copies the file to the other bucket 
  
 await 
  
 storage 
  
 . 
 bucket 
 ( 
 srcBucketName 
 ) 
  
 . 
 file 
 ( 
 srcFilename 
 ) 
  
 . 
  copy 
 
 ( 
 copyDestination 
 , 
  
 copyOptions 
 ); 
  
 console 
 . 
 log 
 ( 
  
 `gs:// 
 ${ 
 srcBucketName 
 } 
 / 
 ${ 
 srcFilename 
 } 
 copied to gs:// 
 ${ 
 destBucketName 
 } 
 / 
 ${ 
 destFileName 
 } 
 ` 
  
 ); 
 } 
 copyFile 
 (). 
 catch 
 ( 
 console 
 . 
 error 
 );

    PHP

    For more information, see the Cloud Storage PHP API reference documentation .

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

      use Google\Cloud\Storage\StorageClient; 
 /** 
 * Copy an object to a new name and/or bucket. 
 * 
 * @param string $bucketName The name of your Cloud Storage bucket. 
 *        (e.g. 'my-bucket') 
 * @param string $objectName The name of your Cloud Storage object. 
 *        (e.g. 'my-object') 
 * @param string $newBucketName The destination bucket name. 
 *        (e.g. 'my-other-bucket') 
 * @param string $newObjectName The destination object name. 
 *        (e.g. 'my-other-object') 
 */ 
 function copy_object(string $bucketName, string $objectName, string $newBucketName, string $newObjectName): void 
 { 
 $storage = new StorageClient(); 
 $bucket = $storage->bucket($bucketName); 
 $object = $bucket->object($objectName); 
 $object->copy($newBucketName, ['name' => $newObjectName]); 
 printf('Copied gs://%s/%s to gs://%s/%s' . PHP_EOL, 
 $bucketName, $objectName, $newBucketName, $newObjectName); 
 }

    Python

    For more information, see the Cloud Storage Python API reference documentation .

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

      from 
  
 google.cloud 
  
 import 
  storage 
 
 def 
  
 copy_blob 
 ( 
 bucket_name 
 , 
 blob_name 
 , 
 destination_bucket_name 
 , 
 destination_blob_name 
 , 
 ): 
  
 """Copies a blob from one bucket to another with a new name.""" 
 # bucket_name = "your-bucket-name" 
 # blob_name = "your-object-name" 
 # destination_bucket_name = "destination-bucket-name" 
 # destination_blob_name = "destination-object-name" 
 storage_client 
 = 
  storage 
 
 . 
  Client 
 
 () 
 source_bucket 
 = 
 storage_client 
 . 
  bucket 
 
 ( 
 bucket_name 
 ) 
 source_blob 
 = 
 source_bucket 
 . 
 blob 
 ( 
 blob_name 
 ) 
 destination_bucket 
 = 
 storage_client 
 . 
  bucket 
 
 ( 
 destination_bucket_name 
 ) 
 # Optional: set a generation-match precondition to avoid potential race conditions 
 # and data corruptions. The request to copy is aborted if the object's 
 # generation number does not match your precondition. For a destination 
 # object that does not yet exist, set the if_generation_match precondition to 0. 
 # If the destination object already exists in your bucket, set instead a 
 # generation-match precondition using its generation number. 
 # There is also an `if_source_generation_match` parameter, which is not used in this example. 
 destination_generation_match_precondition 
 = 
 0 
 blob_copy 
 = 
 source_bucket 
 . 
  copy_blob 
 
 ( 
 source_blob 
 , 
 destination_bucket 
 , 
 destination_blob_name 
 , 
 if_generation_match 
 = 
 destination_generation_match_precondition 
 , 
 ) 
 print 
 ( 
 "Blob 
 {} 
 in bucket 
 {} 
 copied to blob 
 {} 
 in bucket 
 {} 
 ." 
 . 
 format 
 ( 
 source_blob 
 . 
 name 
 , 
 source_bucket 
 . 
 name 
 , 
 blob_copy 
 . 
 name 
 , 
 destination_bucket 
 . 
 name 
 , 
 ) 
 )

    Ruby

    For more information, see the Cloud Storage Ruby API reference documentation .

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

      def 
  
 copy_file 
  
 source_bucket_name 
 :, 
  
 source_file_name 
 :, 
  
 destination_bucket_name 
 :, 
  
 destination_file_name 
 : 
  
 # The ID of the bucket the original object is in 
  
 # source_bucket_name = "source-bucket-name" 
  
 # The ID of the GCS object to copy 
  
 # source_file_name = "source-file-name" 
  
 # The ID of the bucket to copy the object to 
  
 # destination_bucket_name = "destination-bucket-name" 
  
 # The ID of the new GCS object 
  
 # destination_file_name = "destination-file-name" 
  
 require 
  
 "google/cloud/storage" 
  
 storage 
  
 = 
  
 Google 
 :: 
 Cloud 
 :: 
  Storage 
 
 . 
  new 
 
  
 bucket 
  
 = 
  
 storage 
 . 
 bucket 
  
 source_bucket_name 
 , 
  
 skip_lookup 
 : 
  
 true 
  
 file 
  
 = 
  
 bucket 
 . 
  file 
 
  
 source_file_name 
  
 destination_bucket 
  
 = 
  
 storage 
 . 
 bucket 
  
 destination_bucket_name 
  
 destination_file 
  
 = 
  
 file 
 . 
  copy 
 
  
 destination_bucket 
 . 
 name 
 , 
  
 destination_file_name 
  
 puts 
  
 " 
 #{ 
 file 
 . 
 name 
 } 
 in 
 #{ 
 bucket 
 . 
 name 
 } 
 copied to " 
  
 \ 
  
 " 
 #{ 
 destination_file 
 . 
 name 
 } 
 in 
 #{ 
 destination_bucket 
 . 
 name 
 } 
 " 
 end

    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 a POST 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 done property 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 a PUT 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 detailspage opens, with the Objectstab selected.

    3. Navigate to the object, which may be located in a folder.

    4. Click the Object overflowmenu ( ) associated with the object.

    5. If you want to give the object a new name in the same bucket, click Rename.

      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, see Troubleshooting .

    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 the Cloud Storage C++ API reference documentation .

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

      namespace 
  
 gcs 
  
 = 
  
 :: 
 google 
 :: 
 cloud 
 :: 
 storage 
 ; 
 using 
  
 :: 
 google 
 :: 
 cloud 
 :: 
 StatusOr 
 ; 
 []( 
 gcs 
 :: 
 Client 
  
 client 
 , 
  
 std 
 :: 
 string 
  
 const 
&  
 bucket_name 
 , 
  
 std 
 :: 
 string 
  
 const 
&  
 old_object_name 
 , 
  
 std 
 :: 
 string 
  
 const 
&  
 new_object_name 
 ) 
  
 { 
  
 StatusOr<gcs 
 :: 
 ObjectMetadata 
>  
 metadata 
  
 = 
  
 client 
 . 
 RewriteObjectBlocking 
 ( 
  
 bucket_name 
 , 
  
 old_object_name 
 , 
  
 bucket_name 
 , 
  
 new_object_name 
 ); 
  
 if 
  
 ( 
 ! 
 metadata 
 ) 
  
 throw 
  
 std 
 :: 
 move 
 ( 
 metadata 
 ). 
 status 
 (); 
  
 google 
 :: 
 cloud 
 :: 
 Status 
  
 status 
  
 = 
  
 client 
 . 
 DeleteObject 
 ( 
 bucket_name 
 , 
  
 old_object_name 
 ); 
  
 if 
  
 ( 
 ! 
 status 
 . 
 ok 
 ()) 
  
 throw 
  
 std 
 :: 
 runtime_error 
 ( 
 status 
 . 
 message 
 ()); 
  
 std 
 :: 
 cout 
 << 
 "Renamed " 
 << 
 old_object_name 
 << 
 " to " 
 << 
 new_object_name 
 << 
 " in bucket " 
 << 
 bucket_name 
 << 
 " 
 \n 
 " 
 ; 
 }

    C#

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

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

      using 
  
  Google.Cloud.Storage.V1 
 
 ; 
 using 
  
 System 
 ; 
 public 
  
 class 
  
 MoveFileSample 
 { 
  
 public 
  
 void 
  
 MoveFile 
 ( 
  
 string 
  
 sourceBucketName 
  
 = 
  
 "your-unique-bucket-name" 
 , 
  
 string 
  
 sourceObjectName 
  
 = 
  
 "your-object-name" 
 , 
  
 string 
  
 targetBucketName 
  
 = 
  
 "target-object-bucket" 
 , 
  
 string 
  
 targetObjectName 
  
 = 
  
 "target-object-name" 
 ) 
  
 { 
  
 var 
  
 storage 
  
 = 
  
  StorageClient 
 
 . 
  Create 
 
 (); 
  
 storage 
 . 
 CopyObject 
 ( 
 sourceBucketName 
 , 
  
 sourceObjectName 
 , 
  
 targetBucketName 
 , 
  
 targetObjectName 
 ); 
  
 storage 
 . 
 DeleteObject 
 ( 
 sourceBucketName 
 , 
  
 sourceObjectName 
 ); 
  
 Console 
 . 
 WriteLine 
 ( 
 $"Moved {sourceObjectName} to {targetObjectName}." 
 ); 
  
 } 
 }

    Go

    For more information, see the Cloud Storage Go API reference documentation .

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

      import 
  
 ( 
  
 "context" 
  
 "fmt" 
  
 "io" 
  
 "time" 
  
 "cloud.google.com/go/storage" 
 ) 
 // moveFile moves an object into another location. 
 func 
  
 moveFile 
 ( 
 w 
  
 io 
 . 
  Writer 
 
 , 
  
 bucket 
 , 
  
 object 
  
 string 
 ) 
  
 error 
  
 { 
  
 // bucket := "bucket-name" 
  
 // object := "object-name" 
  
 ctx 
  
 := 
  
 context 
 . 
 Background 
 () 
  
 client 
 , 
  
 err 
  
 := 
  
 storage 
 . 
 NewClient 
 ( 
 ctx 
 ) 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "storage.NewClient: %w" 
 , 
  
 err 
 ) 
  
 } 
  
 defer 
  
 client 
 . 
 Close 
 () 
  
 ctx 
 , 
  
 cancel 
  
 := 
  
 context 
 . 
 WithTimeout 
 ( 
 ctx 
 , 
  
 time 
 . 
 Second 
 * 
 10 
 ) 
  
 defer 
  
 cancel 
 () 
  
 dstName 
  
 := 
  
 object 
  
 + 
  
 "-rename" 
  
 src 
  
 := 
  
 client 
 . 
  Bucket 
 
 ( 
 bucket 
 ). 
  Object 
 
 ( 
 object 
 ) 
  
 dst 
  
 := 
  
 client 
 . 
  Bucket 
 
 ( 
 bucket 
 ). 
  Object 
 
 ( 
 dstName 
 ) 
  
 // Optional: set a generation-match precondition to avoid potential race 
  
 // conditions and data corruptions. The request to copy the file is aborted 
  
 // if the object's generation number does not match your precondition. 
  
 // For a dst object that does not yet exist, set the DoesNotExist precondition. 
  
 dst 
  
 = 
  
 dst 
 . 
 If 
 ( 
 storage 
 . 
  Conditions 
 
 { 
 DoesNotExist 
 : 
  
 true 
 }) 
  
 // If the destination object already exists in your bucket, set instead a 
  
 // generation-match precondition using its generation number. 
  
 // attrs, err := dst.Attrs(ctx) 
  
 // if err != nil { 
  
 // 	return fmt.Errorf("object.Attrs: %w", err) 
  
 // } 
  
 // dst = dst.If(storage.Conditions{GenerationMatch: attrs.Generation}) 
  
 if 
  
 _ 
 , 
  
 err 
  
 := 
  
 dst 
 . 
  CopierFrom 
 
 ( 
 src 
 ). 
 Run 
 ( 
 ctx 
 ); 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "Object(%q).CopierFrom(%q).Run: %w" 
 , 
  
 dstName 
 , 
  
 object 
 , 
  
 err 
 ) 
  
 } 
  
 if 
  
 err 
  
 := 
  
 src 
 . 
 Delete 
 ( 
 ctx 
 ); 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "Object(%q).Delete: %w" 
 , 
  
 object 
 , 
  
 err 
 ) 
  
 } 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "Blob %v moved to %v.\n" 
 , 
  
 object 
 , 
  
 dstName 
 ) 
  
 return 
  
 nil 
 }

    Java

    For more information, see the Cloud Storage Java API reference documentation .

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

      import 
  
 com.google.cloud.storage. Blob 
 
 ; 
 import 
  
 com.google.cloud.storage. BlobId 
 
 ; 
 import 
  
 com.google.cloud.storage. BlobInfo 
 
 ; 
 import 
  
 com.google.cloud.storage. Storage 
 
 ; 
 import 
  
 com.google.cloud.storage. StorageOptions 
 
 ; 
 public 
  
 class 
 CopyDeleteObject 
  
 { 
  
 public 
  
 static 
  
 void 
  
 copyDeleteObject 
 ( 
  
 String 
  
 projectId 
 , 
  
 String 
  
 sourceBucketName 
 , 
  
 String 
  
 sourceObjectName 
 , 
  
 String 
  
 targetBucketName 
 , 
  
 String 
  
 targetObjectName 
 ) 
  
 { 
  
 // The ID of your GCP project 
  
 // String projectId = "your-project-id"; 
  
 // The ID of your GCS bucket 
  
 // String sourceBucketName = "your-unique-bucket-name"; 
  
 // The ID of your GCS object 
  
 // String sourceObjectName = "your-object-name"; 
  
 // The ID of the bucket to move the object objectName to 
  
 // String targetBucketName = "target-object-bucket" 
  
 // The ID of your GCS object 
  
 // String targetObjectName = "your-new-object-name"; 
  
  Storage 
 
  
 storage 
  
 = 
  
  StorageOptions 
 
 . 
 newBuilder 
 (). 
 setProjectId 
 ( 
 projectId 
 ). 
 build 
 (). 
  getService 
 
 (); 
  
  BlobId 
 
  
 source 
  
 = 
  
  BlobId 
 
 . 
 of 
 ( 
 sourceBucketName 
 , 
  
 sourceObjectName 
 ); 
  
  BlobId 
 
  
 target 
  
 = 
  
  BlobId 
 
 . 
 of 
 ( 
 targetBucketName 
 , 
  
 targetObjectName 
 ); 
  
 // Optional: set a generation-match precondition to avoid potential race 
  
 // conditions and data corruptions. The request returns a 412 error if the 
  
 // preconditions are not met. 
  
  Storage 
 
 . 
 BlobTargetOption 
  
 precondition 
 ; 
  
  BlobInfo 
 
  
 existingTarget 
  
 = 
  
 storage 
 . 
  get 
 
 ( 
 tar get 
BucketName 
 , 
  
 tar get 
ObjectName 
 ); 
  
 if 
  
 ( 
 existingTarget 
  
 == 
  
 null 
 ) 
  
 { 
  
 // For a target object that does not yet exist, set the DoesNotExist precondition. 
  
 // This will cause the request to fail if the object is created before the request runs. 
  
 precondition 
  
 = 
  
  Storage 
 
 . 
 BlobTargetOption 
 . 
 doesNotExist 
 (); 
  
 } 
  
 else 
  
 { 
  
 // If the destination already exists in your bucket, instead set a generation-match 
  
 // precondition. This will cause the request to fail if the existing object's generation 
  
 // changes before the request runs. 
  
 precondition 
  
 = 
  
  Storage 
 
 . 
 BlobTargetOption 
 . 
 generationMatch 
 ( 
 existingTarget 
 . 
  getGeneration 
 
 ()); 
  
 } 
  
 // Copy source object to target object 
  
 storage 
 . 
  copy 
 
 ( 
  
 Storage 
 . 
 CopyRequest 
 . 
 newBuilder 
 (). 
 setSource 
 ( 
 source 
 ). 
 setTarget 
 ( 
 target 
 , 
  
 precondition 
 ). 
 build 
 ()); 
  
  Blob 
 
  
 copiedObject 
  
 = 
  
 storage 
 . 
  get 
 
 ( 
 tar get 
 
 ); 
  
 // Delete the original blob now that we've copied to where we want it, finishing the "move" 
  
 // operation 
  
 storage 
 . 
  get 
 
 ( 
 source 
 ). 
 delete 
 (); 
  
 System 
 . 
 out 
 . 
 println 
 ( 
  
 "Moved object " 
  
 + 
  
 sourceObjectName 
  
 + 
  
 " from bucket " 
  
 + 
  
 sourceBucketName 
  
 + 
  
 " to " 
  
 + 
  
 targetObjectName 
  
 + 
  
 " in bucket " 
  
 + 
  
 copiedObject 
 . 
 getBucket 
 ()); 
  
 } 
 }

    Node.js

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

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

      /** 
 * TODO(developer): Uncomment the following lines before running the sample. 
 */ 
 // The ID of your GCS bucket 
 // const bucketName = 'your-source-bucket'; 
 // The ID of your GCS file 
 // const srcFileName = 'your-file-name'; 
 // The new ID for your GCS file 
 // const destFileName = 'your-new-file-name'; 
 // Imports the Google Cloud client library 
 const 
  
 { 
 Storage 
 } 
  
 = 
  
 require 
 ( 
 ' @google-cloud/storage 
' 
 ); 
 // Creates a client 
 const 
  
 storage 
  
 = 
  
 new 
  
 Storage 
 (); 
 async 
  
 function 
  
 moveFile 
 () 
  
 { 
  
 // Optional: 
  
 // Set a generation-match precondition to avoid potential race conditions 
  
 // and data corruptions. The request to copy is aborted if the object's 
  
 // generation number does not match your precondition. For a destination 
  
 // object that does not yet exist, set the ifGenerationMatch precondition to 0 
  
 // If the destination object already exists in your bucket, set instead a 
  
 // generation-match precondition using its generation number. 
  
 const 
  
 moveOptions 
  
 = 
  
 { 
  
 preconditionOpts 
 : 
  
 { 
  
 ifGenerationMatch 
 : 
  
 destinationGenerationMatchPrecondition 
 , 
  
 }, 
  
 }; 
  
 // Moves the file within the bucket 
  
 await 
  
 storage 
  
 . 
 bucket 
 ( 
 bucketName 
 ) 
  
 . 
 file 
 ( 
 srcFileName 
 ) 
  
 . 
  move 
 
 ( 
 destFileName 
 , 
  
 moveOptions 
 ); 
  
 console 
 . 
 log 
 ( 
  
 `gs:// 
 ${ 
 bucketName 
 } 
 / 
 ${ 
 srcFileName 
 } 
 moved to gs:// 
 ${ 
 bucketName 
 } 
 / 
 ${ 
 destFileName 
 } 
 ` 
  
 ); 
 } 
 moveFile 
 (). 
 catch 
 ( 
 console 
 . 
 error 
 );

    PHP

    For more information, see the Cloud Storage PHP API reference documentation .

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

      use Google\Cloud\Storage\StorageClient; 
 /** 
 * Move an object to a new name and/or bucket. 
 * 
 * @param string $bucketName The name of your Cloud Storage bucket. 
 *        (e.g. 'my-bucket') 
 * @param string $objectName The name of your Cloud Storage object. 
 *        (e.g. 'my-object') 
 * @param string $newBucketName the destination bucket name. 
 *        (e.g. 'my-other-bucket') 
 * @param string $newObjectName the destination object name. 
 *        (e.g. 'my-other-object') 
 */ 
 function move_object(string $bucketName, string $objectName, string $newBucketName, string $newObjectName): void 
 { 
 $storage = new StorageClient(); 
 $bucket = $storage->bucket($bucketName); 
 $object = $bucket->object($objectName); 
 $object->copy($newBucketName, ['name' => $newObjectName]); 
 $object->delete(); 
 printf('Moved gs://%s/%s to gs://%s/%s' . PHP_EOL, 
 $bucketName, 
 $objectName, 
 $newBucketName, 
 $newObjectName); 
 }

    Python

    For more information, see the Cloud Storage Python API reference documentation .

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

      from 
  
 google.cloud 
  
 import 
  storage 
 
 def 
  
 move_blob 
 ( 
 bucket_name 
 , 
 blob_name 
 , 
 destination_bucket_name 
 , 
 destination_blob_name 
 ,): 
  
 """Moves a blob from one bucket to another with a new name.""" 
 # The ID of your GCS bucket 
 # bucket_name = "your-bucket-name" 
 # The ID of your GCS object 
 # blob_name = "your-object-name" 
 # The ID of the bucket to move the object to 
 # destination_bucket_name = "destination-bucket-name" 
 # The ID of your new GCS object (optional) 
 # destination_blob_name = "destination-object-name" 
 storage_client 
 = 
  storage 
 
 . 
  Client 
 
 () 
 source_bucket 
 = 
 storage_client 
 . 
  bucket 
 
 ( 
 bucket_name 
 ) 
 source_blob 
 = 
 source_bucket 
 . 
 blob 
 ( 
 blob_name 
 ) 
 destination_bucket 
 = 
 storage_client 
 . 
  bucket 
 
 ( 
 destination_bucket_name 
 ) 
 # Optional: set a generation-match precondition to avoid potential race conditions 
 # and data corruptions. The request is aborted if the object's 
 # generation number does not match your precondition. For a destination 
 # object that does not yet exist, set the if_generation_match precondition to 0. 
 # If the destination object already exists in your bucket, set instead a 
 # generation-match precondition using its generation number. 
 # There is also an `if_source_generation_match` parameter, which is not used in this example. 
 destination_generation_match_precondition 
 = 
 0 
 blob_copy 
 = 
 source_bucket 
 . 
  copy_blob 
 
 ( 
 source_blob 
 , 
 destination_bucket 
 , 
 destination_blob_name 
 , 
 if_generation_match 
 = 
 destination_generation_match_precondition 
 , 
 ) 
 source_bucket 
 . 
  delete_blob 
 
 ( 
 blob_name 
 ) 
 print 
 ( 
 "Blob 
 {} 
 in bucket 
 {} 
 moved to blob 
 {} 
 in bucket 
 {} 
 ." 
 . 
 format 
 ( 
 source_blob 
 . 
 name 
 , 
 source_bucket 
 . 
 name 
 , 
 blob_copy 
 . 
 name 
 , 
 destination_bucket 
 . 
 name 
 , 
 ) 
 )

    Ruby

    For more information, see the Cloud Storage Ruby API reference documentation .

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

      def 
  
 move_file 
  
 bucket_name 
 :, 
  
 file_name 
 :, 
  
 new_name 
 : 
  
 # The ID of your GCS bucket 
  
 # bucket_name = "your-unique-bucket-name" 
  
 # The ID of your GCS object 
  
 # file_name = "your-file-name" 
  
 # The ID of your new GCS object 
  
 # new_name = "your-new-file-name" 
  
 require 
  
 "google/cloud/storage" 
  
 storage 
  
 = 
  
 Google 
 :: 
 Cloud 
 :: 
  Storage 
 
 . 
  new 
 
  
 bucket 
  
 = 
  
 storage 
 . 
 bucket 
  
 bucket_name 
 , 
  
 skip_lookup 
 : 
  
 true 
  
 file 
  
 = 
  
 bucket 
 . 
  file 
 
  
 file_name 
  
 renamed_file 
  
 = 
  
 file 
 . 
  copy 
 
  
 new_name 
  
 file 
 . 
 delete 
  
 puts 
  
 " 
 #{ 
 file_name 
 } 
 has been renamed to 
 #{ 
 renamed_file 
 . 
 name 
 } 
 " 
 end

    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

    To atomically rename an object, do the following:

    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 a Objects: 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

    Design a Mobile Site
    View Site in Mobile | Classic
    Share by: