Change object storage classes

This page describes how to change thestorage class of objectswithin a bucket through rewriting the object.

  • To learn how to change object storage classes without rewriting an object,see theObject Lifecycle Management feature.
  • To learn how Cloud Storage can automatically manage your object'sstorage classes, see theAutoclass feature.

Required roles

In order to get the required permissions for changing the storage class ofan object through rewriting the object, ask your administrator to grant you theStorage Object User (roles/storage.objectUser) role on the bucket.

This role contains the permissions required to change the storage class of anobject. To see the exact permissions that are required, expand theRequired permissions section:

Required permissions

  • storage.objects.create
  • storage.objects.delete
  • storage.objects.get
  • storage.objects.list

You might also be able to get these permissions with otherpredefined roles orcustom roles.

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

Change an object's storage class

Complete the following steps to change an object's storage class:

Console

Individual object storage classes cannot be set through theGoogle Cloud console. Instead, use the Google Cloud CLI.

Command line

Use thegcloud storage objects update command with the--storage-class flag. For example:

gcloud storage objects update gs://BUCKET_NAME/OBJECT_NAME --storage-class=STORAGE_CLASS

Where:

  • BUCKET_NAME is the name of the bucketcontaining the object whose class you want to change. For example,my-bucket.
  • OBJECT_NAME is the name of the object whoseclass you want to change. For example,pets/dog.png.
  • STORAGE_CLASS is the newstorage classfor your object. For example,nearline.

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&object_name,std::stringconst&storage_class){StatusOr<gcs::ObjectMetadata>object_metadata=client.RewriteObjectBlocking(bucket_name,object_name,bucket_name,object_name,gcs::WithObjectMetadata(gcs::ObjectMetadata().set_storage_class(storage_class)));if(!object_metadata)throwstd::move(object_metadata).status();std::cout <<"Changed storage class of object " <<object_metadata->name()            <<" in bucket " <<object_metadata->bucket() <<" to "            <<object_metadata->storage_class() <<"\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;publicclassChangeFileStorageClassSample{publicGoogle.Apis.Storage.v1.Data.ObjectChangeFileStorageClass(stringbucketName="your-bucket-name",stringobjectName="your-object-name",stringstorageClass=StorageClasses.Standard){varstorage=StorageClient.Create();// Changing storage class requires a rewrite operation, which can only be done// by the underlying servicevarobj=newGoogle.Apis.Storage.v1.Data.Object{StorageClass=storageClass};storage.Service.Objects.Rewrite(obj,bucketName,objectName,bucketName,objectName).Execute();varfile=storage.GetObject(bucketName,objectName);Console.WriteLine($"Object {objectName} in bucket {bucketName} had"+$" its storage class set to {storageClass}.");returnfile;}}

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")// changeObjectStorageClass changes the storage class of a single object.funcchangeObjectStorageClass(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()o:=client.Bucket(bucket).Object(object)// 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.attrs,err:=o.Attrs(ctx)iferr!=nil{returnfmt.Errorf("object.Attrs: %w",err)}o=o.If(storage.Conditions{GenerationMatch:attrs.Generation})// See the StorageClass documentation for other valid storage classes:// https://cloud.google.com/storage/docs/storage-classesnewStorageClass:="COLDLINE"// You can't change an object's storage class directly, the only way is// to rewrite the object with the desired storage class.copier:=o.CopierFrom(o)copier.StorageClass=newStorageClassif_,err:=copier.Run(ctx);err!=nil{returnfmt.Errorf("copier.Run: %w",err)}fmt.Fprintf(w,"Object %v in bucket %v had its storage class set to %v\n",object,bucket,newStorageClass)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.StorageClass;importcom.google.cloud.storage.StorageOptions;publicclassChangeObjectStorageClass{publicstaticvoidchangeObjectStorageClass(StringprojectId,StringbucketName,StringobjectName){// The ID of your GCP project// String projectId = "your-project-id";// The ID of your GCS bucket// String bucketName = "your-unique-bucket-name";// The ID of your GCS object// String objectName = "your-object-name";Storagestorage=StorageOptions.newBuilder().setProjectId(projectId).build().getService();BlobIdblobId=BlobId.of(bucketName,objectName);BlobsourceBlob=storage.get(blobId);if(sourceBlob==null){System.out.println("The object "+objectName+" wasn't found in "+bucketName);return;}// See the StorageClass documentation for other valid storage classes:// https://googleapis.dev/java/google-cloud-clients/latest/com/google/cloud/storage/StorageClass.htmlStorageClassstorageClass=StorageClass.COLDLINE;// You can't change an object's storage class directly, the only way is to rewrite the object// with the desired storage classBlobInfotargetBlob=BlobInfo.newBuilder(blobId).setStorageClass(storageClass).build();// Optional: set a generation-match precondition to avoid potential race// conditions and data corruptions. The request to upload returns a 412 error if// the object's generation number does not match your precondition.Storage.BlobSourceOptionprecondition=Storage.BlobSourceOption.generationMatch(sourceBlob.getGeneration());Storage.CopyRequestrequest=Storage.CopyRequest.newBuilder().setSource(blobId).setSourceOptions(precondition)// delete this line to run without preconditions.setTarget(targetBlob).build();BlobupdatedBlob=storage.copy(request).getResult();System.out.println("Object "+objectName+" in bucket "+bucketName+" had its storage class set to "+updatedBlob.getStorageClass().name());}}

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.

// Imports the Google Cloud client libraryconst{Storage}=require('@google-cloud/storage');// Creates a clientconststorage=newStorage();/** * TODO(developer): Uncomment the following lines before running the sample. */// The ID of your GCS bucket// const bucketName = 'your-unique-bucket-name';// The ID of your GCS file// const fileName = 'your-file-name';// The name of a storage class// See the StorageClass documentation for other valid storage classes:// https://googleapis.dev/java/google-cloud-clients/latest/com/google/cloud/storage/StorageClass.html// const storageClass = 'coldline';asyncfunctionfileChangeStorageClass(){// 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.constsetStorageClassOptions={ifGenerationMatch:generationMatchPrecondition,};awaitstorage.bucket(bucketName).file(fileName).setStorageClass(storageClass,setStorageClassOptions);console.log(`${fileName} has been set to${storageClass}`);}fileChangeStorageClass().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;/** * Change the storage class of the given file. * * @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 $storageClass The storage class of the new object. *        (e.g. 'COLDLINE') */function change_file_storage_class(string $bucketName, string $objectName, string $storageClass): void{    $storage = new StorageClient();    $bucket = $storage->bucket($bucketName);    $object = $bucket->object($objectName);    // Storage class cannot be changed directly. But we can rewrite the object    // using the new storage class.    $newObject = $object->rewrite($bucket, [        'storageClass' => $storageClass,    ]);    printf(        'Object %s in bucket %s had its storage class set to %s',        $objectName,        $bucketName,        $newObject->info()['storageClass']    );}

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.cloudimportstoragedefchange_file_storage_class(bucket_name,blob_name):"""Change the default storage class of the blob"""# bucket_name = "your-bucket-name"# blob_name = "your-object-name"storage_client=storage.Client()bucket=storage_client.bucket(bucket_name)blob=bucket.blob(blob_name)generation_match_precondition=None# 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.blob.reload()# Fetch blob metadata to use in generation_match_precondition.generation_match_precondition=blob.generationblob.update_storage_class("NEARLINE",if_generation_match=generation_match_precondition)print("Blob{} in bucket{} had its storage class set to{}".format(blob_name,bucket_name,blob.storage_class))returnblob

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.

defchange_file_storage_classbucket_name:,file_name:# The ID of your GCS bucket# bucket_name = "your-unique-bucket-name"# The ID of your GCS object# file_name = "your-file-name"require"google/cloud/storage"storage=Google::Cloud::Storage.newbucket=storage.bucketbucket_name,skip_lookup:truefile=bucket.filefile_namefile.storage_class="NEARLINE"puts"File#{file_name} in bucket#{bucket_name} had its storage class set to#{file.storage_class}"end

REST APIs

JSON API

Caution: ACLs that you want to retain from the original object must beincluded in the object resource that you provide in the request body.
  1. Have gcloud CLIinstalled and initialized, which lets you generate an access token for theAuthorization header.

  2. Create a JSON file that contains the following information:

    {"storageClass":"STORAGE_CLASS"}

    Where:

  3. UsecURL to call theJSON API with aPOST Object, request:

    curl -X POST --data-binary @JSON_FILE_NAME \  -H "Authorization: Bearer $(gcloud auth print-access-token)" \  -H "Content-Type: application/json" \  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME/rewriteTo/b/BUCKET_NAME/o/OBJECT_NAME"

    Where:

    • JSON_FILE_NAME is the path for the JSONfile that you created in Step 2.
    • BUCKET_NAME is the name of the bucketcontaining the original object. For example,my-bucket.
    • OBJECT_NAME is the URL-encoded name of theobject. For example,pets/dog.png, URL-encoded aspets%2Fdog.png.

XML API

Caution: Metadata that you want to retain from the original object,such as custom metadata, must be included in the headers that youprovide in the request. Additionally, any ACLs for the object thatdiffer from the containing bucket's default object ACLs must bereapplied after the object is uploaded.
  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 --data-binary @OBJECT \  -H "Authorization: Bearer $(gcloud auth print-access-token)" \  -H "Content-Type:OBJECT_CONTENT_TYPE" \  -H "x-goog-storage-class:STORAGE_CLASS" \  "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME"

    Where:

    • OBJECT is the local path to the objectwhose storage class you want to change (you must re-upload theobject when changing storage class with the XML API). For example,Desktop/dog.png.
    • OBJECT_CONTENT_TYPE is thecontent type of the object. For example,image/png.
    • STORAGE_CLASS is the newstorage class for your object. For example,nearline.
    • BUCKET_NAME is the name of the bucketcontaining the object you are rewriting. For example,my-bucket.
    • OBJECT_NAME is the URL-encoded name of theobject you are rewriting. For example,pets/dog.png, URL-encodedaspets%2Fdog.png.
Note: This guide involves rewriting data, which is aClass A operation andwhich might incur additional charges, depending on the age, location, andstorage class of the data. For more information, seeCloud Storage pricing. Also note that if you have enabledObject Versioning for your bucket, the original object remains in yourbucket until it is explicitly deleted.

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.