All Products
Search

This Product

    Object Storage Service:put-bucket-versioning

    Document Center

    Object Storage Service:put-bucket-versioning

    Last Updated:Mar 20, 2026

    Configures the versioning state of a bucket.

    Prerequisites

    Before you begin, make sure you have:

    • The PutBucketVersioning permission on the bucket

    Usage notes

    A bucket can be in one of three versioning states:

    StateBehavior
    Disabled (default)Versioning is off. Objects have no version IDs.
    EnabledOSS generates a unique version ID for every object uploaded. All versions are retained.
    SuspendedOSS assigns version ID null to newly uploaded objects. Deleted or overwritten objects do not generate new versions.

    For more information about versioning, see Overview.

    Command syntax

    ossutil api put-bucket-versioning --bucket <bucket-name> --versioning-configuration <config> [flags]

    Parameters

    ParameterTypeRequiredDescription
    --bucketstringYesThe name of the bucket.
    --versioning-configurationstringYesThe versioning configuration. Accepts XML or JSON. Valid Status values: Enabled, Suspended.
    Note

    put-bucket-versioning maps to the PutBucketVersioning API operation. For all supported flags, see Command-line options.

    --versioning-configuration format

    Pass the configuration as a file reference or an inline JSON string.

    XML format:

    <VersioningConfiguration>
  <Status>Enabled</Status>
</VersioningConfiguration>

    JSON format:

    {
  "Status": "Enabled"
}

    Examples

    Enable versioning

    Using an XML configuration file:

    <?xml version="1.0" encoding="UTF-8"?>
<VersioningConfiguration>
  <Status>Enabled</Status>
</VersioningConfiguration>
    ossutil api put-bucket-versioning --bucket examplebucket --versioning-configuration file://versioning-configuration.xml

    Using a JSON configuration file:

    {
  "Status": "Enabled"
}
    ossutil api put-bucket-versioning --bucket examplebucket --versioning-configuration file://versioning-configuration.json

    Using inline JSON:

    ossutil api put-bucket-versioning --bucket examplebucket --versioning-configuration "{\"Status\":\"Enabled\"}"

    Suspend versioning

    ossutil api put-bucket-versioning --bucket examplebucket --versioning-configuration "{\"Status\":\"Suspended\"}"

    What's next