Using Object Versioning

Go to concepts

This page describes how to enable, disable, and check the status of Object Versioning on a bucket. See Working with versioned objects to learn how to list, restore, and delete the objects that are retained by Object Versioning.

Setting Object Versioning

To enable or disable Object Versioning on a bucket:

Console

In the Google Cloud Console, go to the Cloud Storage Browser page.

Go to Browser
In the list of buckets, click on the name of the bucket on which you want to enable or disable Object Versioning.
Select the Protection tab near the top of the page.

The current status of Object versioning is found in the Object versioning section
In the Object versioning section, click the current status to make changes to it.

The Object versioning dialog box appears.
1. If you're enabling Object Versioning and you want to minimize storage costs, select the Add recommended lifecycle rules to manage version costs checkbox.
Click Confirm.

gsutil

Use the gsutil versioning set command:

gsutil versioning set STATE gs://BUCKET_NAME

Where:

STATE is either on to enable Object Versioning or off to disable Object Versioning.
BUCKET_NAME is the name of the relevant bucket. For example, my-bucket.

Code samples

C++

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

The following sample enables Object Versioning on a bucket:

View on GitHub Feedback

namespace gcs = ::google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name) {
  StatusOr<gcs::BucketMetadata> original =
      client.GetBucketMetadata(bucket_name);
  if (!original) throw std::runtime_error(original.status().message());

  StatusOr<gcs::BucketMetadata> patched = client.PatchBucket(
      bucket_name,
      gcs::BucketMetadataPatchBuilder().SetVersioning(
          gcs::BucketVersioning{true}),
      gcs::IfMetagenerationMatch(original->metageneration()));
  if (!patched) throw std::runtime_error(patched.status().message());

  if (patched->versioning().has_value()) {
    std::cout << "Object versioning for bucket " << bucket_name << " is "
              << (patched->versioning()->enabled ? "enabled" : "disabled")
              << "\n";
  } else {
    std::cout << "Object versioning for bucket " << bucket_name
              << " is disabled.\n";
  }
}

The following sample disables Object Versioning on a bucket:

View on GitHub Feedback

namespace gcs = ::google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name) {
  StatusOr<gcs::BucketMetadata> original =
      client.GetBucketMetadata(bucket_name);
  if (!original) throw std::runtime_error(original.status().message());

  StatusOr<gcs::BucketMetadata> patched = client.PatchBucket(
      bucket_name,
      gcs::BucketMetadataPatchBuilder().SetVersioning(
          gcs::BucketVersioning{false}),
      gcs::IfMetagenerationMatch(original->metageneration()));
  if (!patched) throw std::runtime_error(patched.status().message());

  auto versioning =
      patched->versioning().value_or(gcs::BucketVersioning{false});
  std::cout << "Object versioning for bucket " << bucket_name << " is "
            << (versioning.enabled ? "enabled" : "disabled") << "\n";
}

C#

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

The following sample enables Object Versioning on a bucket:

View on GitHub Feedback


using Google.Apis.Storage.v1.Data;
using Google.Cloud.Storage.V1;
using System;

public class BucketEnableVersioningSample
{
	public Bucket BucketEnableVersioning(string bucketName = "your-bucket-name")
	{
		var storage = StorageClient.Create();
		var bucket = storage.GetBucket(bucketName);

		if (bucket.Versioning == null)
		{
			bucket.Versioning = new Bucket.VersioningData();
		}
		bucket.Versioning.Enabled = true;

		bucket = storage.UpdateBucket(bucket);
		Console.WriteLine($"Versioning is now enabled for bucket {bucketName}.");
		return bucket;
	}
}

The following sample disables Object Versioning on a bucket:

View on GitHub Feedback


using Google.Apis.Storage.v1.Data;
using Google.Cloud.Storage.V1;
using System;

public class BucketDisableVersioningSample
{
	public Bucket BucketDisableVersioning(string bucketName = "your-bucket-name")
	{
		var storage = StorageClient.Create();
		var bucket = storage.GetBucket(bucketName);

		if (bucket.Versioning?.Enabled != true)
		{
			Console.WriteLine($"Versioning already disabled for bucket {bucketName}.");
		}
		else
		{
        	    bucket.Versioning.Enabled = false;

		    bucket = storage.UpdateBucket(bucket);
                    Console.WriteLine($"Versioning is now disabled for bucket {bucketName}.");
                }
		return bucket;
	}
}

Go

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

The following sample enables Object Versioning on a bucket:

View on GitHub Feedback

import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/storage"
)

// enableVersioning enables object versioning on a bucket.
func enableVersioning(w io.Writer, bucketName string) error {
	// bucketName := "bucket-name"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %v", err)
	}
	defer client.Close()

	ctx, cancel := context.WithTimeout(ctx, time.Second*10)
	defer cancel()

	bucket := client.Bucket(bucketName)
	bucketAttrsToUpdate := storage.BucketAttrsToUpdate{
		VersioningEnabled: true,
	}
	if _, err := bucket.Update(ctx, bucketAttrsToUpdate); err != nil {
		return fmt.Errorf("Bucket(%q).Update: %v", bucketName, err)
	}
	fmt.Fprintf(w, "Versioning was enabled for %v\n", bucketName)
	return nil
}

The following sample disables Object Versioning on a bucket:

View on GitHub Feedback

import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/storage"
)

// disableVersioning disables object versioning on a bucket.
func disableVersioning(w io.Writer, bucketName string) error {
	// bucketName := "bucket-name"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %v", err)
	}
	defer client.Close()

	ctx, cancel := context.WithTimeout(ctx, time.Second*10)
	defer cancel()

	bucket := client.Bucket(bucketName)
	bucketAttrsToUpdate := storage.BucketAttrsToUpdate{
		VersioningEnabled: false,
	}
	if _, err := bucket.Update(ctx, bucketAttrsToUpdate); err != nil {
		return fmt.Errorf("Bucket(%q).Update: %v", bucketName, err)
	}
	fmt.Fprintf(w, "Versioning was disabled for %v\n", bucketName)
	return nil
}

Java

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

The following sample enables Object Versioning on a bucket:

View on GitHub Feedback

import com.google.cloud.storage.Bucket;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

public class EnableBucketVersioning {
  public static void enableBucketVersioning(String projectId, String bucketName) {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    Bucket bucket = storage.get(bucketName);
    bucket.toBuilder().setVersioningEnabled(true).build().update();

    System.out.println("Versioning is now enabled for bucket " + bucketName);
  }
}

The following sample disables Object Versioning on a bucket:

View on GitHub Feedback

import com.google.cloud.storage.Bucket;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

public class DisableBucketVersioning {
  public static void disableBucketVersioning(String projectId, String bucketName) {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    Bucket bucket = storage.get(bucketName);
    bucket.toBuilder().setVersioningEnabled(false).build().update();

    System.out.println("Versioning is now disabled for bucket " + bucketName);
  }
}

Node.js

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

The following sample enables Object Versioning on a bucket:

View on GitHub Feedback

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

async function enableBucketVersioning() {
  await storage.bucket(bucketName).setMetadata({
    versioning: {
      enabled: true,
    },
  });

  console.log(`Versioning is enabled for bucket ${bucketName}`);
}

enableBucketVersioning().catch(console.error);

The following sample disables Object Versioning on a bucket:

View on GitHub Feedback

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

async function disableBucketVersioning() {
  await storage.bucket(bucketName).setMetadata({
    versioning: {
      enabled: false,
    },
  });

  console.log(`Versioning is disabled for bucket ${bucketName}`);
}

disableBucketVersioning().catch(console.error);

PHP

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

The following sample enables Object Versioning on a bucket:

View on GitHub Feedback

use Google\Cloud\Storage\StorageClient;

/**
 * Enable versioning on the specified bucket.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 */
function enable_versioning($bucketName)
{
    // $bucketName = 'my-bucket';

    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $bucket->update([
        'versioning' => [
            'enabled' => true,
        ]
    ]);

    printf('Versioning is now enabled for bucket %s', $bucketName);
}

The following sample disables Object Versioning on a bucket:

View on GitHub Feedback

use Google\Cloud\Storage\StorageClient;

/**
 * Disable versioning of the given bucket.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 */
function disable_versioning($bucketName)
{
    // $bucketName = 'my-bucket';

    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $bucket->update([
        'versioning' => [
            'enabled' => false,
        ]
    ]);

    printf('Versioning is now disabled for bucket %s', $bucketName);
}

Python

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

The following sample enables Object Versioning on a bucket:

View on GitHub Feedback

from google.cloud import storage


def enable_versioning(bucket_name):
    """Enable versioning for this bucket."""
    # bucket_name = "my-bucket"

    storage_client = storage.Client()

    bucket = storage_client.get_bucket(bucket_name)
    bucket.versioning_enabled = True
    bucket.patch()

    print("Versioning was enabled for bucket {}".format(bucket.name))
    return bucket

The following sample disables Object Versioning on a bucket:

View on GitHub Feedback

from google.cloud import storage


def disable_versioning(bucket_name):
    """Disable versioning for this bucket."""
    # bucket_name = "my-bucket"

    storage_client = storage.Client()

    bucket = storage_client.get_bucket(bucket_name)
    bucket.versioning_enabled = False
    bucket.patch()

    print("Versioning was disabled for bucket {}".format(bucket))
    return bucket

Ruby

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

The following sample enables Object Versioning on a bucket:

View on GitHub Feedback

def enable_versioning bucket_name:
  # The ID of your GCS bucket
  # bucket_name = "your-unique-bucket-name"

  require "google/cloud/storage"

  storage = Google::Cloud::Storage.new
  bucket = storage.bucket bucket_name

  bucket.versioning = true

  puts "Versioning was enabled for bucket #{bucket_name}"
end

The following sample disables Object Versioning on a bucket:

View on GitHub Feedback

def disable_versioning bucket_name:
  # The ID of your GCS bucket
  # bucket_name = "your-unique-bucket-name"

  require "google/cloud/storage"

  storage = Google::Cloud::Storage.new
  bucket = storage.bucket bucket_name

  bucket.versioning = false

  puts "Versioning was disabled for bucket #{bucket_name}"
end

REST APIs

JSON API

Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Create a .json file that contains the following information:
```
{
  "versioning": {
    "enabled": STATE
  }
}
```
Where STATE is either true or false.
Use cURL to call the JSON API with a PATCH Bucket request:
```
curl -X PATCH --data-binary @JSON_FILE_NAME.json \
  -H "Authorization: Bearer OAUTH2_TOKEN" \
  -H "Content-Type: application/json" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?fields=versioning"
```
Where:
- JSON_FILE_NAME is the path and name you created in Step 2.
- OAUTH2_TOKEN is the access token you created in Step 1.
- BUCKET_NAME is the name of the relevant bucket. For example, my-bucket.

XML API

Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Create an .xml file that contains the following information:
```
<VersioningConfiguration>
  <Status>STATE</Status>
</VersioningConfiguration>
```
Where STATE is either Enabled or Suspended.
Use cURL to call the XML API, with a PUT Bucket request and versioning query string parameter:
```
curl -X PUT --data-binary @XML_FILE_NAME.xml \
  -H "Authorization: Bearer OAUTH2_TOKEN" \
  "https://storage.googleapis.com/BUCKET_NAME?versioning"
```
Where:
- XML_FILE_NAME is the path and name you created in Step 2.
- OAUTH2_TOKEN is the access token you created in Step 1.
- BUCKET_NAME is the name of the relevant bucket. For example, my-bucket.

Once Object Versioning is enabled, each time a live object version is replaced or deleted, that version becomes a noncurrent version.

Checking whether Object Versioning is enabled

To check whether Object Versioning is enabled on a bucket:

Console

In the Google Cloud Console, go to the Cloud Storage Browser page.

Go to Browser
In the list of buckets, the Object Versioning status of each bucket is found in the Protection column.

If enabled, the text Object versioning appears.

gsutil

Use the gsutil versioning get command:

gsutil versioning get gs://BUCKET_NAME

Where BUCKET_NAME is the name of the relevant bucket. For example, my-bucket.

The response looks like the following if Object Versioning is enabled:

gs://my-bucket: Enabled

REST APIs

JSON API

Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Use cURL to call the JSON API with a GET Bucket request:
```
curl -X GET \
  -H "Authorization: Bearer OAUTH2_TOKEN" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?fields=versioning"
```
Where:
- OAUTH2_TOKEN is the access token you created in Step 1.
- BUCKET_NAME is the name of the relevant bucket. For example, my-bucket.

XML API

Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Use cURL to call the XML API, with a GET Bucket request and versioning query string parameter:
```
curl -X GET \
  -H "Authorization: Bearer OAUTH2_TOKEN" \
  "https://storage.googleapis.com/BUCKET_NAME?versioning"
```
Where:
- OAUTH2_TOKEN is the access token you created in Step 1.
- BUCKET_NAME is the name of the relevant bucket. For example, my-bucket.

What's next

Learn more about Object Versioning.
Work with noncurrent objects.
Learn how to use Object Lifecycle Management to automatically manage object versions.