This page shows you how to copy, rename, and move objects within and between buckets in Cloud Storage.
Note that while some tools in Cloud Storage make an object move or rename appear to be a unique operation, they are always a copy operation followed by a delete operation of the original object, because objects are immutable.
Copy an object
Roles required
In order to get the required permissions for copying an object, ask your
administrator to grant you the Storage Object Viewer
(roles/storage.objectViewer
) role on the source bucket and the
Storage Object User (roles/storage.objectUser
) role on the
destination bucket. If you plan on using the Google Cloud console, ask your
administrator to grant you the `Viewer` basic role on the projects that contain
the source and destination buckets, in addition to granting the Storage Object
Viewer and Storage Object User roles.
These roles contain the following permissions, which are required to copy an object:
storage.objects.get
on the source bucketstorage.objects.create
on the destination bucketstorage.objects.delete
on the destination bucket (only required if overwriting an object)
When using the Google Cloud console, you must also have the following permissions:
storage.objects.list
on the source and destination bucketsstorage.buckets.list
on the projects that contain the source and destination buckets
If the object you want to copy has enabled features, you might need
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.
You might be able to get these permissions with custom roles or other predefined roles.
For instructions on granting roles on buckets, see Use IAM with buckets.
For instructions on granting roles on projects, see Manage access to projects.
To copy an object in one of your Cloud Storage buckets:
- In the Google Cloud console, go to the Cloud Storage Buckets page.
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.
Navigate to the object, which may be located in a folder.
Click the Object overflow menu (more_vert) associated with the object.
Click Copy.
The Copy object pane appears.
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.
Click Copy.
To learn how to get detailed error information about failed Cloud Storage operations in the Google Cloud console, see Troubleshooting.
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
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.
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.
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.
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.
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.
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.
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.
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.
Have gcloud CLI installed and initialized, which lets you generate an access token for the
Authorization
header.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 aspets%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 additionalrewrite
requests:{ "kind": "storage#rewriteResponse", "totalBytesRewritten": 1048576, "objectSize": 10000000000, "done": false, "rewriteToken":
TOKEN_VALUE }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 therewriteToken
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 totrue
, there is norewriteToken
property, and the metadata of the copy is included in theresource
property.{ "kind": "storage#rewriteResponse", "totalBytesRewritten": 10000000000, "objectSize": 10000000000, "done": true, "resource": objects Resource }
Have gcloud CLI installed and initialized, which lets you generate an access token for the
Authorization
header.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 an object
Roles required
In order to get the required permissions for moving or renaming an object,
ask your administrator to grant you the Storage Object User
(roles/storage.objectUser
) role on both the source bucket and
the destination bucket. If you plan on using the Google Cloud console, ask
your administrator to grant you the `Viewer` basic role on the projects that
contain the source and destination buckets, in addition to granting the Storage
Object User role.
These roles contain the following permissions, which are required to move or rename an object:
storage.objects.delete
on the source bucket (also required on the destination bucket if overwriting an object)storage.objects.get
on the source bucketstorage.objects.create
on the destination bucket
When using the Google Cloud console, you must also have the following permissions:
storage.objects.list
on the source and destination bucketsstorage.buckets.list
on the projects that contain the source and destination buckets
If the object you want to move or rename has enabled features, you might need
alternative roles. For example, if the object you want to move has
an object retention configuration, 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.
You might be able to get these permissions with custom roles or other predefined roles.
For instructions on granting roles on buckets, see Use IAM with buckets.
For instructions on granting roles on projects, see Manage access to projects.
To move an object in Cloud Storage between buckets, or rename an object within a bucket:
- In the Google Cloud console, go to the Cloud Storage Buckets page.
In the list of buckets, click the name of the bucket that contains the object you want to move or rename.
The Bucket details page opens, with the Objects tab selected.
Navigate to the object, which may be located in a folder.
Click the Object overflow menu (more_vert) associated with the object.
If you want to give the object a new name in the same bucket, click Rename.
In the overlay window that appears, enter a new name for the object.
Click Rename.
If you want to move the object to a different bucket, click Move.
In the overlay window that appears, click Browse.
Select the destination for the object you are moving.
Click Select.
Click Move.
To learn how to get detailed error information about failed Cloud Storage operations in the Google Cloud console, see Troubleshooting.
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 storing your moved or renamed object. 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
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.
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.
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.
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.
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.
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.
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.
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.
To move or rename an object using the JSON API directly, first make a copy of the object that has the properties you want and then delete the original object.
To move or rename an object using the XML API directly, first make a copy of the object that has the properties you want and then delete the original object.
We recommend using Storage Transfer Service to move more than 1 TB of data between buckets.
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.