---
title: "Versioning"
description: "Keep earlier versions of a bucket's objects when they are overwritten or deleted, and list, read, restore and delete them."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.ezghcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Versioning

With versioning enabled, a bucket keeps every version of its objects.

- Overwriting an object adds a new version, which becomes the current one. The earlier versions stay.
- Deleting an object adds a delete marker. The object no longer appears in listings and reads answer
  `404`, while its versions stay.
- Every version has a version ID. Standard S3 tools list, read, copy and delete versions by ID.

A bucket's versioning is Off, Enabled or Suspended. Once enabled, it can be suspended but not turned
off.

| Status | Writes | Deletes |
| --- | --- | --- |
| Off | Replace the object | Remove the object |
| Enabled | Add a version | Add a delete marker |
| Suspended | Replace the version with ID `null`. Versions made while enabled stay | Replace the version with ID `null` with a delete marker |

Objects written before versioning was enabled have the version ID `null`.

## Enable versioning

Changing a bucket's versioning needs `objects.buckets.update`.

### Console

1. Open the bucket and select **Versioning**.
2. Select **Enable**.
3. Select **Enable versioning** to confirm.
### CLI

With `ezgh` 0.71.0 or later:

```sh
ezgh objects buckets settings my-bucket --versioning enabled
ezgh objects buckets get my-bucket
```
### AWS CLI

```sh
export AWS_PROFILE=ezgh

aws s3api put-bucket-versioning --bucket my-bucket --versioning-configuration Status=Enabled
aws s3api get-bucket-versioning --bucket my-bucket
```

See [AWS CLI](/object-storage/aws-cli) for the profile.
### boto3

With the client from [boto3](/object-storage/boto3):

```python
s3.put_bucket_versioning(Bucket="my-bucket", VersioningConfiguration={"Status": "Enabled"})

status = s3.get_bucket_versioning(Bucket="my-bucket").get("Status")
```
### Terraform

The Terraform AWS provider's `aws_s3_bucket_versioning` sets a bucket's versioning:

```hcl
provider "aws" {
  region     = "us-west-1"
  access_key = "oak_…"
  secret_key = "…"

  endpoints {
    s3 = "https://s3.us-west-1.ezghapps.com"
  }

  s3_use_path_style           = true
  skip_credentials_validation = true
  skip_requesting_account_id  = true
  skip_region_validation      = true
}

resource "aws_s3_bucket_versioning" "my_bucket" {
  bucket = "my-bucket"

  versioning_configuration {
    status = "Enabled"
  }
}
```
### API

[PutBucketVersioning](/objects-api/PutBucketVersioning/) in the Object Storage API takes
`enabled` or `suspended`. A bucket's `versioning` is `null` until versioning is first enabled.

MFA Delete isn't supported: a `PutBucketVersioning` that enables it answers `NotImplemented`.

## List versions

Listing versions needs `objects.objects.list`.

In the console, open the bucket, select **Objects** and turn on **Show versions**. The list shows
every version and delete marker under the current prefix. The current version of each object is
marked **Latest**.

### AWS CLI

```sh
aws s3api list-object-versions --bucket my-bucket --prefix reports/
```

`Versions` holds the versions and `DeleteMarkers` the delete markers. `IsLatest` is `true` on the
current one of each key.
### boto3

```python
pages = s3.get_paginator("list_object_versions").paginate(Bucket="my-bucket", Prefix="reports/")
for page in pages:
    for version in page.get("Versions", []):
        print(version["Key"], version["VersionId"], version["IsLatest"], version["Size"])
    for marker in page.get("DeleteMarkers", []):
        print(marker["Key"], marker["VersionId"], marker["IsLatest"], "delete marker")
```
### API

[ListObjectVersions](/objects-api/ListObjectVersions/) in the Object Storage API.

## Read a version

Reading a version needs `objects.objects.download`. In the console, select a version and then
**Download**.

```sh
aws s3api get-object --bucket my-bucket --key reports/q3.pdf --version-id "$VERSION_ID" q3.pdf
aws s3api head-object --bucket my-bucket --key reports/q3.pdf --version-id "$VERSION_ID"
```

```python
body = s3.get_object(Bucket="my-bucket", Key="reports/q3.pdf", VersionId=version_id)["Body"].read()
```

A version ID that names a delete marker, or no version, answers `404`.

A read by version ID always needs credentials. [Public-read buckets](/object-storage/public-buckets-and-presigned-urls)
and [CDN distributions](/cdn/guides/serve-a-private-bucket) serve current objects only, and answer
`403 AccessDenied` to a request with a `versionId`.

## Restore an object

To restore a deleted object, delete its delete marker. The version before it becomes current again.
Find the marker's ID under `DeleteMarkers` in the version listing, with `IsLatest` `true`:

```sh
aws s3api delete-object --bucket my-bucket --key reports/q3.pdf --version-id "$MARKER_ID"
```

In the console, select the delete marker marked **Latest** in the versions list, then **Delete**.

To go back to an earlier version of an object that was overwritten, copy that version over the
object. The copy becomes a new current version, and every earlier version stays:

```sh
aws s3api copy-object --bucket my-bucket --key reports/q3.pdf \
  --copy-source "my-bucket/reports/q3.pdf?versionId=$VERSION_ID"
```

```python
s3.copy_object(
    Bucket="my-bucket",
    Key="reports/q3.pdf",
    CopySource={"Bucket": "my-bucket", "Key": "reports/q3.pdf", "VersionId": version_id},
)
```

## Delete a version

Deleting a version needs `objects.objects.delete`.

> **Caution**
>
> Deleting a version by its ID is permanent. No delete marker is added.

```sh
aws s3api delete-object --bucket my-bucket --key reports/q3.pdf --version-id "$VERSION_ID"
```

```python
s3.delete_object(Bucket="my-bucket", Key="reports/q3.pdf", VersionId=version_id)
```

`DeleteObjects` takes a `VersionId` for each key. In the console, select a version and then
**Delete**.

A bucket must hold no versions and no delete markers to be deleted.

## Suspend versioning

Suspending keeps every version there is. New writes and deletes no longer add versions: they replace
the version with ID `null`.

### Console

Open the bucket, select **Versioning**, then **Suspend**.
### CLI

```sh
ezgh objects buckets settings my-bucket --versioning suspended
```
### AWS CLI

```sh
aws s3api put-bucket-versioning --bucket my-bucket --versioning-configuration Status=Suspended
```

Enable versioning again the same way as the first time.

## Storage and lifecycle

Every version counts toward your organization's [storage](/object-storage/limits). A bucket's usage
counts objects including versions.

[Lifecycle rules](/object-storage/lifecycle-rules) delete versions a number of days after a newer
version replaces them, and remove delete markers that are the only version left of their object.

## Supported S3 operations

| Operation | Notes |
| --- | --- |
| `GetBucketVersioning`, `PutBucketVersioning` | `Enabled` and `Suspended`. MFA Delete answers `NotImplemented` |
| `ListObjectVersions` | |
| `GetObject`, `HeadObject` | `versionId` |
| `DeleteObject`, `DeleteObjects` | `versionId` |
| `CopyObject`, `UploadPartCopy` | `versionId` on the copy source |

## Conditional writes

Of concurrent [conditional writes](/object-storage#conditional-writes) of one key, with
`If-None-Match` or `If-Match`, one succeeds. The others answer `412`, or
`409 ConditionalRequestConflict` while the first is still being written. Retry a `409`.

## Permissions

| To | You need |
| --- | --- |
| View a bucket's versioning | `objects.buckets.get` |
| Enable or suspend versioning | `objects.buckets.update` |
| List versions and delete markers | `objects.objects.list` |
| Read or copy from a version | `objects.objects.download` |
| Delete a version or a delete marker | `objects.objects.delete` |

These apply to the console, the CLI, the API and S3 requests alike. See
[Permissions](/object-storage/access-keys#permissions).

## Trails

Trails records changes to a bucket's versioning. It doesn't record version listings, reads or
deletes.

Source: https://docs.ezghcloud.com/object-storage/versioning/index.mdx
