Copy, rename, and move objects

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

Caution: Because moving objects by copying them includes deleting the originalobjects from the source bucket, using this method to moveobjects whose storage class is Nearline storage, Coldline storage, orArchive storage can incurearly deletion charges. If youmove objects atomically, no early deletion charges are incurred, regardlessof the storage class of the objects being moved.

We recommend usingStorage Transfer Service to move more than 1 TB of databetween buckets.

Before you begin

In order to copy, rename, or move objects, you must get the requiredIAM roles. The following sections describe IAMrequirements 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 toroles/storage.objectViewer androles/storage.objectUser

These predefined roles contain the permissions required to copy objects. To see the exact permissions that are required, expand theRequired 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 withcustom roles.

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

If the object you want to copy has certain features enabled, you might needadditional or alternative roles. For example, if the object you want to copy hasan object retention configuration you want to retain, you'll need a role onthe destination bucket that includes thestorage.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 theRequired 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 withcustom roles.

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

Copy objects

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

Note: If you are copying an object larger than 2 GB across differentregions or storage classes, we recommend you use the gcloud CLIfor optimal performance.

Console

  1. In the Google Cloud console, go to the Cloud StorageBuckets page.

    Go to Buckets

  2. In the list of buckets, click the name of the bucket that containsthe object you want to copy.

    TheBucket details page opens, with theObjects tab selected.

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

  4. Click theObject overflow menu() associatedwith the object.

  5. ClickCopy.

    TheCopy object pane appears.

  6. In theDestination field, type the name of the destination bucketand the name for the copied object.

    You can alternatively clickBrowse to select your destination, butbrowse options are limited to buckets in the current project.

  7. ClickCopy.

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

Command line

Use thegcloud 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 bucketcontaining the object you want to copy. For example,my-bucket.
  • SOURCE_OBJECT_NAME is the name of the objectyou want to copy. For example,pets/dog.png.
  • DESTINATION_BUCKET_NAME is the name of thebucket where you want to copy your object. For example,another-bucket.
  • NAME_OF_COPY is the name you want to give thecopy 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 StorageC++ API reference documentation.

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

namespacegcs=::google::cloud::storage;using::google::cloud::StatusOr;[](gcs::Clientclient,std::stringconst&source_bucket_name,std::stringconst&source_object_name,std::stringconst&destination_bucket_name,std::stringconst&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)throwstd::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()            <<".\nThe full metadata after the copy is: " <<*new_copy_meta            <<"\n";}

C#

For more information, see theCloud StorageC# API reference documentation.

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

usingGoogle.Cloud.Storage.V1;usingSystem;publicclassCopyFileSample{publicvoidCopyFile(stringsourceBucketName="source-bucket-name",stringsourceObjectName="source-file",stringdestBucketName="destination-bucket-name",stringdestObjectName="destination-file-name"){varstorage=StorageClient.Create();storage.CopyObject(sourceBucketName,sourceObjectName,destBucketName,destObjectName);Console.WriteLine($"Copied {sourceBucketName}/{sourceObjectName} to "+$"{destBucketName}/{destObjectName}.");}}

Go

For more information, see theCloud StorageGo API reference documentation.

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

import("context""fmt""io""time""cloud.google.com/go/storage")// copyFile copies an object into specified bucket.funccopyFile(wio.Writer,dstBucket,srcBucket,srcObjectstring)error{// dstBucket := "bucket-1"// srcBucket := "bucket-2"// srcObject := "object"ctx:=context.Background()client,err:=storage.NewClient(ctx)iferr!=nil{returnfmt.Errorf("storage.NewClient: %w",err)}deferclient.Close()ctx,cancel:=context.WithTimeout(ctx,time.Second*10)defercancel()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{returnfmt.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)returnnil}

Java

For more information, see theCloud StorageJava API reference documentation.

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

importcom.google.cloud.storage.BlobId;importcom.google.cloud.storage.BlobInfo;importcom.google.cloud.storage.CopyWriter;importcom.google.cloud.storage.Storage;importcom.google.cloud.storage.Storage.CopyRequest;importcom.google.cloud.storage.StorageOptions;publicclassCopyObject{publicstaticvoidcopyObject(StringprojectId,StringsourceBucketName,StringobjectName,StringtargetBucketName)throwsException{// 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(Storagestorage=StorageOptions.newBuilder().setProjectId(projectId).build().getService()){BlobIdsourceId=BlobId.of(sourceBucketName,objectName);// you could change "objectName" to rename the objectBlobIdtargetId=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.BlobTargetOptionprecondition;BlobInfoexistingTarget=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());}CopyRequestcopyRequest=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();CopyWritercopyWriter=storage.copy(copyRequest);BlobInfosuccessfulCopyResult=copyWriter.getResult();System.out.printf("Copied object gs://%s/%s to %s%n",sourceBucketName,objectName,successfulCopyResult.getBlobId().toGsUtilUriWithGeneration());}}}

Node.js

For more information, see theCloud StorageNode.js API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet 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 libraryconst{Storage}=require('@google-cloud/storage');// Creates a clientconststorage=newStorage();asyncfunctioncopyFile(){constcopyDestination=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.constcopyOptions={preconditionOpts:{ifGenerationMatch:destinationGenerationMatchPrecondition,},};// Copies the file to the other bucketawaitstorage.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 theCloud StoragePHP API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet 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 theCloud StoragePython API reference documentation.

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

fromgoogle.cloudimportstoragedefcopy_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=0blob_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 theCloud StorageRuby API reference documentation.

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

defcopy_filesource_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.newbucket=storage.bucketsource_bucket_name,skip_lookup:truefile=bucket.filesource_file_namedestination_bucket=storage.bucketdestination_bucket_namedestination_file=file.copydestination_bucket.name,destination_file_nameputs"#{file.name} in#{bucket.name} copied to "\"#{destination_file.name} in#{destination_bucket.name}"end

REST APIs

JSON API

  1. Have gcloud CLIinstalled and initialized, which lets you generate an access token for theAuthorization header.

  2. UsecURL to call theJSON 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 thebucket containing the object you want to copy. For example,my-bucket.
    • SOURCE_OBJECT_NAME is the URL-encoded nameof the object you want to copy. For example,pets/dog.png,URL-encoded aspets%2Fdog.png.
    • DESTINATION_BUCKET_NAME is the name ofthe bucket where you want to copy your object. For example,another-bucket.
    • NAME_OF_COPY is the URL-encoded name youwant to give the copy of your object. For example,shiba.png.

    Since therewrite method copies data in limited-sized chunks, yourcopy might require multiple requests, especially for large objects.

    For example, the following response to arewrite request indicatesthat you need to make additionalrewrite requests:

    {  "kind": "storage#rewriteResponse",  "totalBytesRewritten": 1048576,  "objectSize": 10000000000,  "done": false,  "rewriteToken":TOKEN_VALUE}
  3. Use therewriteToken in a subsequent request to continue copyingdata:

    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 therewriteToken valuereturned 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 adoneproperty set totrue, there is norewriteToken property, andthe metadata of the copy is included in theresource property.

    { "kind": "storage#rewriteResponse", "totalBytesRewritten": 10000000000, "objectSize": 10000000000, "done": true, "resource":objects Resource}

XML API

  1. Have gcloud CLIinstalled and initialized, which lets you generate an access token for theAuthorization header.

  2. UsecURL to call theXML 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 thebucket containing the object you want to copy. For example,my-bucket.
    • SOURCE_OBJECT_NAME is the name of theobject you want to copy. For example,pets/dog.png.
    • DESTINATION_BUCKET_NAME is the name ofthe bucket where you want to copy your object. For example,another-bucket.
    • NAME_OF_COPY is the URL-encoded name youwant 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 objectcopy operations. The tools described in this section perform object moves andrenames by copying the original object to another namespace and then deletingthe original object.

Note: If you are moving an object larger than 2 GB across differentregions or storage classes, we recommend you use the gcloud CLIfor optimal performance.

Console

  1. In the Google Cloud console, go to the Cloud StorageBuckets page.

    Go to Buckets

  2. In the list of buckets, click the name of the bucket that containsthe object you want to move.

    TheBucket details page opens, with theObjects tab selected.

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

  4. Click theObject overflow menu() associatedwith 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. ClickRename.

  6. If you want to move the object to a different bucket, clickMove.

    1. In the overlay window that appears, clickBrowse.

    2. Select the destination for the object you are moving.

    3. ClickSelect.

    4. ClickMove.

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

Command line

Use thegcloud 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 bucketcontaining the object you want to move or rename. For example,my-bucket.
  • SOURCE_OBJECT_NAME is the name of the objectyou want to move or rename. For example,pets/dog.png.
  • DESTINATION_BUCKET_NAME is the name of thebucket you want to move the object to. For example,another-bucket.
  • DESTINATION_OBJECT_NAME is the name you wantyour 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.txtRemoving gs://example-bucket/old-file.txt...  Completed files 1/1 | 164.3kiB/164.3kiB

Client libraries

C++

For more information, see theCloud StorageC++ API reference documentation.

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

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

C#

For more information, see theCloud StorageC# API reference documentation.

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

usingGoogle.Cloud.Storage.V1;usingSystem;publicclassMoveFileSample{publicvoidMoveFile(stringsourceBucketName="your-unique-bucket-name",stringsourceObjectName="your-object-name",stringtargetBucketName="target-object-bucket",stringtargetObjectName="target-object-name"){varstorage=StorageClient.Create();storage.CopyObject(sourceBucketName,sourceObjectName,targetBucketName,targetObjectName);storage.DeleteObject(sourceBucketName,sourceObjectName);Console.WriteLine($"Moved {sourceObjectName} to {targetObjectName}.");}}

Go

For more information, see theCloud StorageGo API reference documentation.

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

import("context""fmt""io""time""cloud.google.com/go/storage")// moveFile moves an object into another location.funcmoveFile(wio.Writer,bucket,objectstring)error{// bucket := "bucket-name"// object := "object-name"ctx:=context.Background()client,err:=storage.NewClient(ctx)iferr!=nil{returnfmt.Errorf("storage.NewClient: %w",err)}deferclient.Close()ctx,cancel:=context.WithTimeout(ctx,time.Second*10)defercancel()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{returnfmt.Errorf("Object(%q).CopierFrom(%q).Run: %w",dstName,object,err)}iferr:=src.Delete(ctx);err!=nil{returnfmt.Errorf("Object(%q).Delete: %w",object,err)}fmt.Fprintf(w,"Blob %v moved to %v.\n",object,dstName)returnnil}

Java

For more information, see theCloud StorageJava API reference documentation.

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

importcom.google.cloud.storage.Blob;importcom.google.cloud.storage.BlobId;importcom.google.cloud.storage.BlobInfo;importcom.google.cloud.storage.Storage;importcom.google.cloud.storage.StorageOptions;publicclassCopyDeleteObject{publicstaticvoidcopyDeleteObject(StringprojectId,StringsourceBucketName,StringsourceObjectName,StringtargetBucketName,StringtargetObjectName){// 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";Storagestorage=StorageOptions.newBuilder().setProjectId(projectId).build().getService();BlobIdsource=BlobId.of(sourceBucketName,sourceObjectName);BlobIdtarget=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.BlobTargetOptionprecondition;BlobInfoexistingTarget=storage.get(targetBucketName,targetObjectName);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 objectstorage.copy(Storage.CopyRequest.newBuilder().setSource(source).setTarget(target,precondition).build());BlobcopiedObject=storage.get(target);// Delete the original blob now that we've copied to where we want it, finishing the "move"// operationstorage.get(source).delete();System.out.println("Moved object "+sourceObjectName+" from bucket "+sourceBucketName+" to "+targetObjectName+" in bucket "+copiedObject.getBucket());}}

Node.js

For more information, see theCloud StorageNode.js API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet 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 libraryconst{Storage}=require('@google-cloud/storage');// Creates a clientconststorage=newStorage();asyncfunctionmoveFile(){// 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.constmoveOptions={preconditionOpts:{ifGenerationMatch:destinationGenerationMatchPrecondition,},};// Moves the file within the bucketawaitstorage.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 theCloud StoragePHP API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet 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 theCloud StoragePython API reference documentation.

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

fromgoogle.cloudimportstoragedefmove_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=0blob_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 theCloud StorageRuby API reference documentation.

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

defmove_filebucket_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.newbucket=storage.bucketbucket_name,skip_lookup:truefile=bucket.filefile_namerenamed_file=file.copynew_namefile.deleteputs"#{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,seeCopy objects.

XML API

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

Rename objects atomically

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

REST APIs

JSON API

  1. Have gcloud CLIinstalled and initialized, which lets you generate an access token for theAuthorization header.

  2. UsecURL to call theJSON 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 thebucket containing the object you want to rename. For example,my-bucket.
    • SOURCE_OBJECT_NAME is the URL-encodedname of the object you want to rename. For example,pets/dog.png, URL-encoded aspets%2Fdog.png.
    • DESTINATION_OBJECT_NAME is theURL-encoded name you want to use. For example,pets/cat.png,URL-encoded aspets%2Fcat.png.

What's next

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

Last updated 2026-02-19 UTC.