Help Center/ Object Storage Service/ User Guide/ Data Security/ Using Versioning to Restore Data and Manage Object Versions/ Enabling, Suspending, and Viewing Versioning
Updated on 2026-08-21 GMT+08:00
View PDF
Share

Enabling, Suspending, and Viewing Versioning

Scenarios

By default, versioning is disabled for a new OBS bucket. New objects with the same name will overwrite existing objects in the bucket.

A versioning-enabled bucket can retain multiple versions of an object, making it easier to retrieve and restore any version. This feature also helps you quickly recover data in the event of accidental actions or application failures. You can enable versioning for a bucket or resume versioning if it has been suspended.

Versioning cannot be disabled once it is enabled. If you no longer need this function, you can suspend it instead.

Constraints

  • Once versioning is enabled for a bucket, it cannot be disabled, but it can be suspended.
  • Before enabling bucket-level WORM, you must enable versioning. Configuring WORM on OBS Console automatically enables versioning for the bucket, and versioning cannot be suspended afterward. When configuring WORM using APIs, you must first call the API that enables versioning for the bucket.
  • ACLs, server-side encryption, and tags cannot be configured for historical object versions.

Billing

Versioning itself is free. However, storing the current version (excluding the delete marker) and all historical versions of each object incurs storage costs. To avoid unnecessary storage costs, delete objects promptly. You can either delete them manually or configure lifecycle rules to automate deletion.

Configuring Versioning

You can use OBS Console, APIs, or SDKs to configure versioning for a bucket. You cannot use OBS Browser+ or obsutil to do so.

Using OBS Console

  1. In the navigation pane of OBS Console, choose Buckets.
  2. In the bucket list, click the desired bucket. The Objects page is displayed.
  3. In the navigation pane, choose Overview.
  4. In the Basic Configurations area, click Versioning.

    Alternatively, in the navigation pane, choose Data Security > Versioning.

    Figure 1 Editing versioning status

  5. Enable or suspend versioning.

    • On the Versioning page, enable Versioning and click Save.
      Figure 2 Enabling versioning
    • On the Versioning page, disable Versioning and click Save. Versioning is then suspended.
      Figure 3 Suspending versioning

Using APIs

Using SDKs

Configure Versioning

Java

Python

C

Go

BrowserJS

.NET

Android

iOS

PHP

Node.js

Obtain Versioning Status

Java

Python

C

Go

BrowserJS

.NET

Android

iOS

PHP

Node.js

Viewing Object Versions (When Versioning Is Enabled or Suspended)

Before viewing object versions, make sure versioning has been enabled or suspended for your bucket.

You can use OBS Console, APIs, SDKs, or obsutil to view object versions. You cannot use OBS Browser+ to do so.

Using OBS Console

  1. In the navigation pane of OBS Console, choose Buckets.
  2. Enable Historical Versions above the object list.

    The object list displays both the current version and historical versions (including deleted objects with delete markers). Each object version has a unique version ID.

    Figure 4 Viewing object versions

Using APIs

Listing Objects in a Bucket

Using SDKs

Java

Python

C

Go

BrowserJS

.NET

Android

iOS

PHP

Node.js

Using the CLI Tool - obsutil

Command Line Structure

  • Windows 
    obsutil ls obs://bucket[/prefix] [-s] [-fs] [-d] [-v] [-du] [-marker=xxx] [-versionIdMarker=xxx]  [-bf=xxx] [-limit=1] [-format=default] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]
  • macOS or Linux 
    ./obsutil ls obs://bucket[/prefix] [-s] [-fs] [-d] [-v] [-du] [-marker=xxx] [-versionIdMarker=xxx]  [-bf=xxx] [-limit=1] [-format=default] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]

Examples

  • Example 1: In Windows, run obsutil ls obs://bucket-test -limit=10 to list a limited number of objects in the bucket. 
    obsutil ls obs://bucket-test -limit=10
Start at 2024-09-30 08:18:50.0592788 +0000 UTC

Listing objects .

Folder list:
obs://bucket-test/api/

Object list:
key                                               LastModified                  Size      StorageClass        ETag                
obs://bucket-test/AUTHORS                         2018-11-16T02:15:49Z          33243     standard            "796393c1eaf502ef56a85c2ceb640aea"

obs://bucket-test/CONTRIBUTING.md                 2018-11-16T02:15:49Z          1366      standard            "12d93325ba6131f852daecd18dd65edc"

obs://bucket-test/CONTRIBUTORS                    2018-11-16T02:15:49Z          45710     standard            "b486b5003e6215c9199e86ab3ccec9fa"

obs://bucket-test/LICENSE                         2018-11-16T02:15:49Z          1479      standard            "5d4950ecb7b26d2c5e4e7b4e0dd74707"

obs://bucket-test/PATENTS                         2018-11-16T02:15:49Z          1303      standard            "3a55d95595a6f9e37dee53826b4daff2"

obs://bucket-test/README.md                       2018-11-16T02:15:49Z          1399      standard            "97351fd7946b9ea021a31a86ba2a10ab"

obs://bucket-test/VERSION                         2018-11-16T02:15:49Z          7         standard            "43d93b553855b0e1fc67e31c28c07b65"

obs://bucket-test/api/README                      2018-11-16T02:15:49Z          521       standard            "4e9e63a87075df60cdf65c8ce9e92117"

obs://bucket-test/api/except.txt                  2018-11-16T02:15:49Z          20194     standard            "8eb96de3f60447e2f09a7531c99fb3ee"

Next marker: api/except.txt
Folder number: 1
File number: 9
  • Example 2: In Windows, run obsutil ls obs://bucket-test2 to list all objects in the bucket. 
    obsutil ls obs://bucket-test2
Start at 2024-09-30 08:21:06.6300221 +0000 UTC

Listing objects .

Object list:
key                                               LastModified                  Size      StorageClass        ETag    
obs://bucket-test2/123                            2022-03-29T09:17:51Z          0B        standard            "d41d8cd98f00b204e9800998ecf8427e"

obs://bucket-test2/1_2-3.txt                      2022-03-29T09:17:51Z          0B        standard            "d41d8cd98f00b204e9800998ecf8427e"

obs://bucket-test2/1_2-3_33.txt                   2022-03-29T09:17:51Z          200B      standard            "dcf204c11d791255adc63e61763c2426"

obs://bucket-test2/New text file.txt
                                                  2022-03-29T09:17:51Z          0B        standard            "d41d8cd98f00b204e9800998ecf8427e"

Total size of bucket: 200B
Folder number: 0
File number: 4
  • Example 3: In Windows, run obsutil ls obs://bucket-test2/prefix to list objects whose name prefix is prefix in the bucket. 
    obsutil ls obs://bucket-test2/prefix
Start at 2024-09-30 08:24:36.7057148 +0000 UTC

Listing objects .

Object list:
key                                               LastModified                  Size      StorageClass        ETag    
obs://bucket-test2/prefix                         2022-03-29T09:17:51Z          0B        standard            "d41d8cd98f00b204e9800998ecf8427e"

obs://bucket-test2/prefix2                        2022-03-29T09:17:51Z          0B        standard            "d41d8cd98f00b204e9800998ecf8427e"

Total size of prefix [prefix]:: 0B
Folder number: 0
File number: 2

Parameter Description

Parameter

Optional or Mandatory

Description

bucket

Mandatory

The bucket name

prefix

Optional

The prefix of the object name for listing objects

NOTE:

If this parameter is left blank, all objects in the bucket are listed.

s

Optional (additional parameter)

Displays simplified query result.

NOTE:

In the simplified format, the returned result contains only the object name.

d

Optional (additional parameter)

Lists only objects and subdirectories in the current directory, instead of recursively listing all objects and subdirectories.

In big data scenarios, parallel file systems usually have deep directory levels and each directory has a large number of files. In such case, you are advised to use this parameter to limit the scope to list.

NOTE:

According to the naming conventions in OBS, a slash (/) is used as the directory separator.

v

Optional (additional parameter)

Lists versions of an object in a bucket. The result contains the latest version and historical versions (if any) of the object.

marker

Optional (additional parameter)

The start position for listing objects in a bucket. The objects following this start position are sorted in lexicographical order by object name.

NOTE:

For details about how to use this parameter, see Listing.

versionIdMarker

Optional (additional parameter). It must be used together with the v and marker parameters.

The start position for listing object versions in a bucket. The object versions following this start position are sorted in lexicographical order by object name.

NOTE:

If the value of versionIdMarker is not a version ID specified by marker, versionIdMarker is invalid.

bf

Optional (additional parameter)

The display formats of bytes in the listing result. The value can be:

  • human-readable
  • raw
NOTE:

If this parameter is not configured, the display format of bytes in the result is determined by the humanReadableFormat parameter in the configuration file.

du

Optional (additional parameter)

Quickly returns the total size of listed objects, without displaying detailed object information. This parameter can be used together with other parameters.

NOTE:

If there are too many objects listed, wait for a while.

CAUTION:

This parameter is only supported by obsutil 5.4.6 and later.

fs

Optional (additional parameter)

Whether the method of listing parallel file systems is applied. If you are listing parallel file systems, you are recommended to add this parameter.

CAUTION:
  • With this method, the listing time required varies largely depending on the directory structures.
  • After this parameter is enabled, marker and limit will be ignored. Then, the size of the bucket, parallel file system, or directory will be calculated.
  • This parameter is only supported by obsutil 5.5.12 and later.

limit

Optional (additional parameter)

The maximum number of objects that can be listed. If the value is less than or equal to 0, all objects are listed. If it is left blank, 1,000 objects are listed by default.

NOTE:

If there are a large number of objects in a bucket, you are advised to set this parameter to limit the number of objects to be listed each time. If not all objects are listed, marker and versionIdMarker of the next request will be returned in the result, which you can use to list the remaining objects.

format

Optional (additional parameter)

Prints a listing result in the user-defined format. Currently, the value can only be default, indicating that the listing result is displayed in one row.

bucket-cname

Optional (additional parameter)

The user-defined domain name bound to the bucket

NOTE:

This parameter is only supported by obsutil 5.7.9 and later.

config

Optional (additional parameter)

The user-defined configuration file for executing the current command. For details about parameters that can be configured, see Configuration Parameters.

e

Optional (additional parameter)

The endpoint

i

Optional (additional parameter)

The user's AK

k

Optional (additional parameter)

The user's SK

t

Optional (additional parameter)

The user's security token

Response

After you run the command to list object versions, OBS displays object versions and delete markers separately in the response, as shown in Figure 5.

Figure 5 Response to the request for listing object versions 
obsutil ls obs://no-delete-bucket-version-obsutil/data_0001.txt -v
Start at 2026-06-17 01:23:35.2387286 +0000 UTC

Listing versioning objects .

Versioning Object list:
Key                           VersionId                               LastModified                  Size      StorageClass        ETag
obs://no-delete-bucket-version-obsutil/data_0001.txt
                              G001119ED0A0BF6800004017005E42D5        2026-06-16T13:30:56Z          0B        standard            "d41d8cd98f00b204e9800998ecf8427e"

DeleteMarker list:
Key                           VersionId                               LastModified                  StorageClass
obs://no-delete-bucket-version-obsutil/data_0001.txt
                              G001119ED32CD9F700004011024A1A22        2026-06-17T01:23:12Z          standard

Total size of prefix [data_0001.txt]: 0B
Folder number: 0
Versioning file number: 1
DeleteMarker number: 1
Table 1 Object list and Versioning Object list response parameters (for common objects and object versions)

Field

Description

Key

The object name

VersionId

The object version ID. If versioning is enabled or suspended for a bucket, this parameter is displayed in the response when you list object versions in the bucket.

LastModified

The time when the last modification was made to the object

Size

The object size

StorageClass

The storage class of an object. The value can be:

  • standard: Standard storage class. It features low access latency and high throughput, and is suitable for storing frequently accessed data (multiple accesses per month) or data that is smaller than 1 MB.
  • warm: Infrequent Access storage class. It is ideal for storing infrequently accessed data (fewer than 12 times a year), but when needed, the access has to be fast.
  • cold: Archive storage class. It provides secure, durable, and inexpensive storage for rarely-accessed data (once a year).
  • deep-archive: Deep Archive storage class. It is ideal for storing data that is hardly ever accessed (once every few years). This storage class costs less than the Archive storage class, but takes longer (usually several hours) to restore data.

ETag

The ETag of an object, which is a Base64-encoded 128-bit MD5 digest. The ETag can be used to check whether the object content has changed, but it cannot be used as the unique identifier of the object. For example, if the ETag value is A when an object is uploaded, but this value has changed to B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the object content, rather than the object metadata. An uploaded object or copied object has a unique ETag.
Table 2 DeleteMarker list response parameters (for delete markers)

Field

Description

Key

The object name

VersionId

The object version ID. If versioning is enabled or suspended for a bucket, this parameter is displayed in the response when you list object versions in the bucket.

LastModified

The time when the last modification was made to the object

StorageClass

The storage class of an object. The value can be:

  • standard: Standard storage class. It features low access latency and high throughput, and is suitable for storing frequently accessed data (multiple accesses per month) or data that is smaller than 1 MB.
  • warm: Infrequent Access storage class. It is ideal for storing infrequently accessed data (fewer than 12 times a year), but when needed, the access has to be fast.
  • cold: Archive storage class. It provides secure, durable, and inexpensive storage for rarely-accessed data (once a year).
  • deep-archive: Deep Archive storage class. It is ideal for storing data that is hardly ever accessed (once every few years). This storage class costs less than the Archive storage class, but takes longer (usually several hours) to restore data.
Parent Topic: Using Versioning to Restore Data and Manage Object Versions