# Working with objects in a versioning-enabled bucket Objects that are stored in an Amazon S3 bucket before you set the versioning state have a version ID of `null`. When you enable versioning, existing objects in your bucket do not change. What changes is how Amazon S3 handles the objects in future requests. **Transitioning object versions** You can define lifecycle configuration rules for objects that have a well-defined lifecycle to transition object versions to the S3 Glacier Flexible Retrieval storage class at a specific time in the object's lifetime. For more information, see [Managing the lifecycle of objects](object-lifecycle-mgmt.md). The topics in this section explain various object operations in a versioning-enabled bucket. For more information about versioning, see [Retaining multiple versions of objects with S3 Versioning](Versioning.md). **Topics** + [Adding objects to versioning-enabled buckets](AddingObjectstoVersioningEnabledBuckets.md) + [Listing objects in a versioning-enabled bucket](list-obj-version-enabled-bucket.md) + [Retrieving object versions from a versioning-enabled bucket](RetrievingObjectVersions.md) + [Deleting object versions from a versioning-enabled bucket](DeletingObjectVersions.md) + [Configuring versioned object permissions](VersionedObjectPermissionsandACLs.md) # Adding objects to versioning-enabled buckets After you enable versioning on a bucket, Amazon S3 automatically adds a unique version ID to every object stored (using `PUT`, `POST`, or `CopyObject`) in the bucket. The following figure shows that Amazon S3 adds a unique version ID to an object when it is added to a versioning-enabled bucket. ![\[Illustration that shows a unique version ID added to an object when it is put in a versioning-enabled bucket.\]](http://docs.aws.amazon.com/AmazonS3/latest/userguide/images/versioning_PUT_versionEnabled.png) **Note** The version ID values that Amazon S3 assigns are URL safe (can be included as part of a URI). For more information about versioning, see [Retaining multiple versions of objects with S3 Versioning](Versioning.md). You can add object versions to a versioning-enabled bucket using the console, AWS SDKs, and REST API. ## Using the console For instructions, see [Uploading objects](upload-objects.md). ## Using the AWS SDKs For examples of uploading objects using the AWS SDKs for Java, .NET, and PHP, see [Uploading objects](upload-objects.md). The examples for uploading objects in nonversioned and versioning-enabled buckets are the same, although in the case of versioning-enabled buckets, Amazon S3 assigns a version number. Otherwise, the version number is null. For information about using other AWS SDKs, see the [AWS Developer Center](https://aws.amazon.com/code/). ## Using the REST API **To add objects to versioning-enabled buckets** 1. Enable versioning on a bucket using a `PutBucketVersioning` request. For more information, see [https://docs.aws.amazon.com/AmazonS3/latest/API/RESTBucketPUTVersioningStatus.html](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTBucketPUTVersioningStatus.html) in the *Amazon Simple Storage Service API Reference*. 1. Send a `PUT`, `POST`, or `CopyObject` request to store an object in the bucket. When you add an object to a versioning-enabled bucket, Amazon S3 returns the version ID of the object in the `x-amz-version-id` response header, as shown in the following example. ``` 1. x-amz-version-id: 3/L4kqtJlcpXroDTDmJ+rmSpXd3dIbrHY ``` # Listing objects in a versioning-enabled bucket This section provides examples of listing object versions from a versioning-enabled bucket. Amazon S3 stores object version information in the *versions* subresource that is associated with the bucket. For more information, see [General purpose buckets configuration options](UsingBucket.md#bucket-config-options-intro). In order to list the objects in a versioning-enabled bucket, you need the `ListBucketVersions` permission. ## Using the S3 console Follow these steps to use the Amazon S3 console to see the different versions of an object. **To see multiple versions of an object** 1. Sign in to the AWS Management Console and open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/). 1. In the **Buckets** list, choose the name of the bucket that contains the object. 1. To see a list of the versions of the objects in the bucket, choose the **Show versions** switch. For each object version, the console shows a unique version ID, the date and time the object version was created, and other properties. (Objects stored in your bucket before you set the versioning state have a version ID of **null**.) To list the objects without the versions, choose the **List versions** switch. You also can view, download, and delete object versions in the object overview pane on the console. For more information, see [Viewing object properties in the Amazon S3 console](view-object-properties.md). **Note** To access object versions older than 300 versions, you must use the AWS CLI or the object's URL. **Important** You can undelete an object only if it was deleted as the latest (current) version. You can't undelete a previous version of an object that was deleted. For more information, see [Retaining multiple versions of objects with S3 Versioning](Versioning.md). ## Using the AWS SDKs The examples in this section show how to retrieve an object listing from a versioning-enabled bucket. Each request returns up to 1,000 versions, unless you specify a lower number. If the bucket contains more versions than this limit, you send a series of requests to retrieve the list of all versions. This process of returning results in "pages" is called *pagination*. To show how pagination works, the examples limit each response to two object versions. After retrieving the first page of results, each example checks to determine whether the version list was truncated. If it was, the example continues retrieving pages until all versions have been retrieved. **Note** The following examples also work with a bucket that isn't versioning-enabled, or for objects that don't have individual versions. In those cases, Amazon S3 returns the object listing with a version ID of `null`. For information about using other AWS SDKs, see the [AWS Developer Center](https://aws.amazon.com/code/). ------ #### [ Java ] For instructions on creating and testing a working sample, see [Getting Started](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/getting-started.html) in the AWS SDK for Java Developer Guide. ``` import com.amazonaws.AmazonServiceException; import com.amazonaws.SdkClientException; import com.amazonaws.auth.profile.ProfileCredentialsProvider; import com.amazonaws.regions.Regions; import com.amazonaws.services.s3.AmazonS3; import com.amazonaws.services.s3.AmazonS3ClientBuilder; import com.amazonaws.services.s3.model.ListVersionsRequest; import com.amazonaws.services.s3.model.S3VersionSummary; import com.amazonaws.services.s3.model.VersionListing; public class ListKeysVersioningEnabledBucket { public static void main(String[] args) { Regions clientRegion = Regions.DEFAULT_REGION; String bucketName = "*** Bucket name ***"; try { AmazonS3 s3Client = AmazonS3ClientBuilder.standard() .withCredentials(new ProfileCredentialsProvider()) .withRegion(clientRegion) .build(); // Retrieve the list of versions. If the bucket contains more versions // than the specified maximum number of results, Amazon S3 returns // one page of results per request. ListVersionsRequest request = new ListVersionsRequest() .withBucketName(bucketName) .withMaxResults(2); VersionListing versionListing = s3Client.listVersions(request); int numVersions = 0, numPages = 0; while (true) { numPages++; for (S3VersionSummary objectSummary : versionListing.getVersionSummaries()) { System.out.printf("Retrieved object %s, version %s\n", objectSummary.getKey(), objectSummary.getVersionId()); numVersions++; } // Check whether there are more pages of versions to retrieve. If // there are, retrieve them. Otherwise, exit the loop. if (versionListing.isTruncated()) { versionListing = s3Client.listNextBatchOfVersions(versionListing); } else { break; } } System.out.println(numVersions + " object versions retrieved in " + numPages + " pages"); } catch (AmazonServiceException e) { // The call was transmitted successfully, but Amazon S3 couldn't process // it, so it returned an error response. e.printStackTrace(); } catch (SdkClientException e) { // Amazon S3 couldn't be contacted for a response, or the client // couldn't parse the response from Amazon S3. e.printStackTrace(); } } } ``` ------ #### [ .NET ] For information about setting up and running the code examples, see [Getting Started with the AWS SDK for .NET](https://docs.aws.amazon.com/sdk-for-net/latest/developer-guide/net-dg-setup.html) in the *AWS SDK for .NET Developer Guide*. ``` using Amazon; using Amazon.S3; using Amazon.S3.Model; using System; using System.Threading.Tasks; namespace Amazon.DocSamples.S3 { class ListObjectsVersioningEnabledBucketTest { static string bucketName = "*** bucket name ***"; // Specify your bucket region (an example region is shown). private static readonly RegionEndpoint bucketRegion = RegionEndpoint.USWest2; private static IAmazonS3 s3Client; public static void Main(string[] args) { s3Client = new AmazonS3Client(bucketRegion); GetObjectListWithAllVersionsAsync().Wait(); } static async Task GetObjectListWithAllVersionsAsync() { try { ListVersionsRequest request = new ListVersionsRequest() { BucketName = bucketName, // You can optionally specify key name prefix in the request // if you want list of object versions of a specific object. // For this example we limit response to return list of 2 versions. MaxKeys = 2 }; do { ListVersionsResponse response = await s3Client.ListVersionsAsync(request); // Process response. foreach (S3ObjectVersion entry in response.Versions) { Console.WriteLine("key = {0} size = {1}", entry.Key, entry.Size); } // If response is truncated, set the marker to get the next // set of keys. if (response.IsTruncated) { request.KeyMarker = response.NextKeyMarker; request.VersionIdMarker = response.NextVersionIdMarker; } else { request = null; } } while (request != null); } catch (AmazonS3Exception e) { Console.WriteLine("Error encountered on server. Message:'{0}' when writing an object", e.Message); } catch (Exception e) { Console.WriteLine("Unknown encountered on server. Message:'{0}' when writing an object", e.Message); } } } } ``` ------ ## Using the REST API **Example — Listing all object versions in a bucket** To list all the versions of all the objects in a bucket, you use the `versions` subresource in a `GET Bucket` request. Amazon S3 can retrieve a maximum of 1,000 objects, and each object version counts fully as an object. Therefore, if a bucket contains two keys (for example, `photo.gif` and `picture.jpg`), and the first key has 990 versions and the second key has 400 versions, a single request would retrieve all 990 versions of `photo.gif` and only the most recent 10 versions of `picture.jpg`. Amazon S3 returns object versions in the order in which they were stored, with the most recently stored returned first. In a `GET Bucket` request, include the `versions` subresource. ``` 1. GET /?versions HTTP/1.1 2. Host: bucketName.s3.amazonaws.com 3. Date: Wed, 28 Oct 2009 22:32:00 +0000 4. Authorization: AWS AKIAIOSFODNN7EXAMPLE:0RQf4/cRonhpaBX5sCYVf1bNRuU= ``` **Example — Retrieving all versions of a key** To retrieve a subset of object versions, you use the request parameters for `GET Bucket`. For more information, see [https://docs.aws.amazon.com/AmazonS3/latest/API/RESTBucketGET.html](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTBucketGET.html). 1. Set the `prefix` parameter to the key of the object that you want to retrieve. 1. Send a `GET Bucket` request using the `versions` subresource and `prefix`. `GET /?versions&prefix=objectName HTTP/1.1` **Example — Retrieving objects using a prefix** The following example retrieves objects whose key is or begins with `myObject`. ``` 1. GET /?versions&prefix=myObject HTTP/1.1 2. Host: bucket.s3.amazonaws.com 3. Date: Wed, 28 Oct 2009 22:32:00 GMT 4. Authorization: AWS AKIAIOSFODNN7EXAMPLE:0RQf4/cRonhpaBX5sCYVf1bNRuU= ``` You can use the other request parameters to retrieve a subset of all versions of the object. For more information, see [https://docs.aws.amazon.com/AmazonS3/latest/API/RESTBucketGET.html](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTBucketGET.html) in the *Amazon Simple Storage Service API Reference*. **Example — Retrieving a listing of additional objects if the response is truncated** If the number of objects that could be returned in a `GET` request exceeds the value of `max-keys`, the response contains `true`, and includes the first key (in `NextKeyMarker`) and the first version ID (in `NextVersionIdMarker`) that satisfy the request, but were not returned. You use those returned values as the starting position in a subsequent request to retrieve the additional objects that satisfy the `GET` request. Use the following process to retrieve additional objects that satisfy the original `GET Bucket versions` request from a bucket. For more information about `key-marker`, `version-id-marker`, `NextKeyMarker`, and `NextVersionIdMarker`, see [https://docs.aws.amazon.com/AmazonS3/latest/API/RESTBucketGET.html](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTBucketGET.html) in the *Amazon Simple Storage Service API Reference*. The following are additional responses that satisfy the original `GET` request: + Set the value of `key-marker` to the key returned in `NextKeyMarker` in the previous response. + Set the value of `version-id-marker` to the version ID returned in `NextVersionIdMarker` in the previous response. + Send a `GET Bucket versions` request using `key-marker` and `version-id-marker`. **Example — Retrieving objects starting with a specified key and version ID** ``` 1. GET /?versions&key-marker=myObject&version-id-marker=298459348571 HTTP/1.1 2. Host: bucket.s3.amazonaws.com 3. Date: Wed, 28 Oct 2009 22:32:00 GMT 4. Authorization: AWS AKIAIOSFODNN7EXAMPLE:0RQf4/cRonhpaBX5sCYVf1bNRuU= ``` ## Using the AWS CLI The following command returns metadata about all versions of the objects in a bucket. ``` aws s3api list-object-versions --bucket amzn-s3-demo-bucket1 ``` For more information about `list-object-versions` see [https://docs.aws.amazon.com/cli/latest/reference/s3api/list-object-versions.html](https://docs.aws.amazon.com/cli/latest/reference/s3api/list-object-versions.html) in the *AWS CLI Command Reference*. # Retrieving object versions from a versioning-enabled bucket Versioning in Amazon S3 is a way of keeping multiple variants of an object in the same bucket. A simple `GET` request retrieves the current version of an object. The following figure shows how `GET` returns the current version of the object, `photo.gif`. ![\[Illustration that shows how GET returns the current version of the object.\]](http://docs.aws.amazon.com/AmazonS3/latest/userguide/images/versioning_GET_NoVersionID.png) To retrieve a specific version, you have to specify its version ID. The following figure shows that a `GET versionId` request retrieves the specified version of the object (not necessarily the current one). ![\[Illustration that shows how a GET versionId request retrieves the specified version of the object.\]](http://docs.aws.amazon.com/AmazonS3/latest/userguide/images/versioning_GET_Versioned.png) You can retrieve object versions in Amazon S3 using the console, AWS SDKs, or REST API. **Note** To access object versions older than 300 versions, you must use the AWS CLI or the object's URL. ## Using the S3 console 1. Sign in to the AWS Management Console and open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/). 1. In the **Buckets** list, choose the name of the bucket that contains the object. 1. In the **Objects** list, choose the name of the object. 1. Choose **Versions**. Amazon S3 shows all the versions for the object. 1. Select the check box next to the **Version ID** for the versions that you want to retrieve. 1. Choose **Actions**, choose **Download**, and save the object. You also can view, download, and delete object versions in the object overview panel. For more information, see [Viewing object properties in the Amazon S3 console](view-object-properties.md). **Important** You can undelete an object only if it was deleted as the latest (current) version. You can't undelete a previous version of an object that was deleted. For more information, see [Retaining multiple versions of objects with S3 Versioning](Versioning.md). ## Using the AWS SDKs The examples for uploading objects in nonversioned and versioning-enabled buckets are the same. However, for versioning-enabled buckets, Amazon S3 assigns a version number. Otherwise, the version number is null. For examples of downloading objects using AWS SDKs for Java, .NET, and PHP, see [Downloading objects](https://docs.aws.amazon.com/AmazonS3/latest/userguide/download-objects.html). For examples of listing the version of objects using AWS SDKs for .NET and Rust, see [List the version of objects in an Amazon S3 bucket](https://docs.aws.amazon.com/code-library/latest/ug/s3_example_s3_ListObjectVersions_section.html). ## Using the REST API **To retrieve a specific object version** 1. Set `versionId` to the ID of the version of the object that you want to retrieve. 1. Send a `GET Object versionId` request. **Example — Retrieving a versioned object** The following request retrieves version `L4kqtJlcpXroDTDmpUMLUo` of `my-image.jpg`. ``` 1. GET /my-image.jpg?versionId=L4kqtJlcpXroDTDmpUMLUo HTTP/1.1 2. Host: bucket.s3.amazonaws.com 3. Date: Wed, 28 Oct 2009 22:32:00 GMT 4. Authorization: AWS AKIAIOSFODNN7EXAMPLE:0RQf4/cRonhpaBX5sCYVf1bNRuU= ``` You can retrieve just the metadata of an object (not the content). For information, see [Retrieving the metadata of an object version](RetMetaOfObjVersion.md). For information about restoring a previous object version, see [Restoring previous versions](RestoringPreviousVersions.md). # Retrieving the metadata of an object version If you only want to retrieve the metadata of an object (and not its content), you use the `HEAD` operation. By default, you get the metadata of the most recent version. To retrieve the metadata of a specific object version, you specify its version ID. **To retrieve the metadata of an object version** 1. Set `versionId` to the ID of the version of the object whose metadata you want to retrieve. 1. Send a `HEAD Object versionId` request. **Example — Retrieving the metadata of a versioned object** The following request retrieves the metadata of version `3HL4kqCxf3vjVBH40Nrjfkd` of `my-image.jpg`. ``` 1. HEAD /my-image.jpg?versionId=3HL4kqCxf3vjVBH40Nrjfkd HTTP/1.1 2. Host: bucket.s3.amazonaws.com 3. Date: Wed, 28 Oct 2009 22:32:00 GMT 4. Authorization: AWS AKIAIOSFODNN7EXAMPLE:0RQf4/cRonhpaBX5sCYVf1bNRuU= ``` The following shows a sample response. ``` 1. HTTP/1.1 200 OK 2. x-amz-id-2: ef8yU9AS1ed4OpIszj7UDNEHGran 3. x-amz-request-id: 318BC8BC143432E5 4. x-amz-version-id: 3HL4kqtJlcpXroDTDmjVBH40Nrjfkd 5. Date: Wed, 28 Oct 2009 22:32:00 GMT 6. Last-Modified: Sun, 1 Jan 2006 12:00:00 GMT 7. ETag: "fba9dede5f27731c9771645a39863328" 8. Content-Length: 434234 9. Content-Type: text/plain 10. Connection: close 11. Server: AmazonS3 ``` # Restoring previous versions You can use versioning to retrieve previous versions of an object. There are two approaches to doing so: + Copy a previous version of the object into the same bucket. The copied object becomes the current version of that object and all object versions are preserved. + Permanently delete the current version of the object. When you delete the current object version, you, in effect, turn the previous version into the current version of that object. Because all object versions are preserved, you can make any earlier version the current version by copying a specific version of the object into the same bucket. In the following figure, the source object (ID = 111111) is copied into the same bucket. Amazon S3 supplies a new ID (88778877) and it becomes the current version of the object. So, the bucket has both the original object version (111111) and its copy (88778877). For more information about getting a previous version and then uploading it to make it the current version, see [Retrieving object versions from a versioning-enabled bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RetrievingObjectVersions.html) and [Uploading objects](https://docs.aws.amazon.com/AmazonS3/latest/userguide/upload-objects.html). ![\[Illustration that shows copying a specific version of an object into the same bucket to make it the current version.\]](http://docs.aws.amazon.com/AmazonS3/latest/userguide/images/versioning_COPY2.png) A subsequent `GET` retrieves version 88778877. The following figure shows how deleting the current version (121212) of an object leaves the previous version (111111) as the current object. For more information about deleting an object, see [Deleting a single object](https://docs.aws.amazon.com/AmazonS3/latest/userguide/delete-objects.html). ![\[Illustration that shows deleting the current version of an object leaves the previous version as the current object.\]](http://docs.aws.amazon.com/AmazonS3/latest/userguide/images/versioning_COPY_delete2.png) A subsequent `GET` retrieves version 111111. **Note** To restore object versions in batches, you can [use the `CopyObject` operation](https://docs.aws.amazon.com/AmazonS3/latest/userguide/batch-ops-copy-object.html). The `CopyObject` operation copies each object that is specified in the manifest. However, be aware that objects aren't necessarily copied in the same order as they appear in the manifest. For versioned buckets, if preserving current/non-current version order is important, you should copy all non-current versions first. Then, after the first job is complete, copy the current versions in a subsequent job. ## To restore previous object versions For more guidance on restoring deleted objects, see [How can I retrieve an Amazon S3 object that was deleted in a versioning-enabled bucket?](https://repost.aws/knowledge-center/s3-undelete-configuration) in the AWS re:Post Knowledge Center. ### Using the S3 console 1. Sign in to the AWS Management Console and open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/). 1. In the **Buckets** list, choose the name of the bucket that contains the object. 1. In the **Objects** list, choose the name of the object. 1. Choose **Versions**. Amazon S3 shows all the versions for the object. 1. Select the check box next to the **Version ID** for the versions that you want to retrieve. 1. Choose **Actions**, choose **Download**, and save the object. You also can view, download, and delete object versions in the object overview panel. For more information, see [Viewing object properties in the Amazon S3 console](view-object-properties.md). **Important** You can undelete an object only if it was deleted as the latest (current) version. You can't undelete a previous version of an object that was deleted. For more information, see [Retaining multiple versions of objects with S3 Versioning](Versioning.md). ### Using the AWS SDKs For information about using other AWS SDKs, see the [AWS Developer Center](https://aws.amazon.com/code/). ------ #### [ Python ] The following Python code example restores a versioned object's previous version by deleting all versions that occurred after the specified rollback version. ``` def rollback_object(bucket, object_key, version_id): """ Rolls back an object to an earlier version by deleting all versions that occurred after the specified rollback version. Usage is shown in the usage_demo_single_object function at the end of this module. :param bucket: The bucket that holds the object to roll back. :param object_key: The object to roll back. :param version_id: The version ID to roll back to. """ # Versions must be sorted by last_modified date because delete markers are # at the end of the list even when they are interspersed in time. versions = sorted( bucket.object_versions.filter(Prefix=object_key), key=attrgetter("last_modified"), reverse=True, ) logger.debug( "Got versions:\n%s", "\n".join( [ f"\t{version.version_id}, last modified {version.last_modified}" for version in versions ] ), ) if version_id in [ver.version_id for ver in versions]: print(f"Rolling back to version {version_id}") for version in versions: if version.version_id != version_id: version.delete() print(f"Deleted version {version.version_id}") else: break print(f"Active version is now {bucket.Object(object_key).version_id}") else: raise KeyError( f"{version_id} was not found in the list of versions for " f"{object_key}." ) ``` ------ # Deleting object versions from a versioning-enabled bucket You can delete object versions from Amazon S3 buckets whenever you want. You can also define lifecycle configuration rules for objects that have a well-defined lifecycle to request Amazon S3 to expire current object versions or permanently remove noncurrent object versions. When your bucket has versioning enabled or the versioning is suspended, the lifecycle configuration actions work as follows: + The `Expiration` action applies to the current object version. Instead of deleting the current object version, Amazon S3 retains the current version as a noncurrent version by adding a *delete marker*, which then becomes the current version. + The `NoncurrentVersionExpiration` action applies to noncurrent object versions, and Amazon S3 permanently removes these object versions. You cannot recover permanently removed objects. For more information about S3 Lifecycle, see [Managing the lifecycle of objects](object-lifecycle-mgmt.md) and [Examples of S3 Lifecycle configurations](lifecycle-configuration-examples.md). To see how many current and noncurrent object versions that your buckets have, you can use Amazon S3 Storage Lens metrics. S3 Storage Lens is a cloud-storage analytics feature that you can use to gain organization-wide visibility into object-storage usage and activity. For more information, see [ Using S3 Storage Lens to optimize your storage costs](https://docs.aws.amazon.com/AmazonS3/latest/userguide/storage-lens-optimize-storage.html?icmpid=docs_s3_user_guide_DeletingObjectVersions.html). For a complete list of metrics, see [ S3 Storage Lens metrics glossary](https://docs.aws.amazon.com/AmazonS3/latest/userguide/storage_lens_metrics_glossary.html?icmpid=docs_s3_user_guide_replication.html). **Note** Normal Amazon S3 rates apply for every version of an object that is stored and transferred, including noncurrent object versions. For more information, see [Amazon S3 pricing](https://aws.amazon.com/s3/pricing/). ## Delete request use cases A `DELETE` request has the following use cases: + When versioning is enabled, a simple `DELETE` cannot permanently delete an object. (A simple `DELETE` request is a request that doesn't specify a version ID.) Instead, Amazon S3 inserts a delete marker in the bucket, and that marker becomes the current version of the object with a new ID. When you try to `GET` an object whose current version is a delete marker, Amazon S3 behaves as though the object has been deleted (even though it has not been erased) and returns a 404 error. For more information, see [Working with delete markers](DeleteMarker.md). The following figure shows that a simple `DELETE` does not actually remove the specified object. Instead, Amazon S3 inserts a delete marker. ![\[Illustration that shows a delete marker insertion.\]](http://docs.aws.amazon.com/AmazonS3/latest/userguide/images/versioning_DELETE_versioningEnabled.png) + To delete versioned objects permanently, you must use `DELETE Object versionId`. The following figure shows that deleting a specified object version permanently removes that object. ![\[Diagram that shows how DELETE Object versionId permanently deletes a specific object version.\]](http://docs.aws.amazon.com/AmazonS3/latest/userguide/images/versioning_DELETE_versioningEnabled2.png) ## To delete object versions You can delete object versions in Amazon S3 using the console, AWS SDKs, the REST API, or the AWS Command Line Interface. ### Using the S3 console 1. Sign in to the AWS Management Console and open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/). 1. In the **Buckets** list, choose the name of the bucket that contains the object. 1. In the **Objects** list, choose the name of the object. 1. Choose **Versions**. Amazon S3 shows all the versions for the object. 1. Select the check box next to the **Version ID** for the versions that you want to permanently delete. 1. Choose **Delete**. 1. In **Permanently delete objects?**, enter **permanently delete**. **Warning** When you permanently delete an object version, the action cannot be undone. 1. Choose **Delete objects**. Amazon S3 deletes the object version. ### Using the AWS SDKs For examples of deleting objects using the AWS SDKs for Java, .NET, and PHP, see [Deleting Amazon S3 objects](DeletingObjects.md). The examples for deleting objects in nonversioned and versioning-enabled buckets are the same. However, for versioning-enabled buckets, Amazon S3 assigns a version number. Otherwise, the version number is null. For information about using other AWS SDKs, see the [AWS Developer Center](https://aws.amazon.com/code/). ------ #### [ Python ] The following Python code example permanently deletes a versioned object by deleting all of its versions. ``` def permanently_delete_object(bucket, object_key): """ Permanently deletes a versioned object by deleting all of its versions. Usage is shown in the usage_demo_single_object function at the end of this module. :param bucket: The bucket that contains the object. :param object_key: The object to delete. """ try: bucket.object_versions.filter(Prefix=object_key).delete() logger.info("Permanently deleted all versions of object %s.", object_key) except ClientError: logger.exception("Couldn't delete all versions of %s.", object_key) raise ``` ------ ### Using the REST API **To delete a specific version of an object** + In a `DELETE`, specify a version ID. **Example — Deleting a specific version** The following example deletes version `UIORUnfnd89493jJFJ` of `photo.gif`. ``` 1. DELETE /photo.gif?versionId=UIORUnfnd89493jJFJ HTTP/1.1 2. Host: bucket.s3.amazonaws.com 3. Date: Wed, 12 Oct 2009 17:50:00 GMT 4. Authorization: AWS AKIAIOSFODNN7EXAMPLE:xQE0diMbLRepdf3YB+FIEXAMPLE= 5. Content-Type: text/plain 6. Content-Length: 0 ``` ### Using the AWS CLI The following command deletes an object named test.txt from a bucket named `amzn-s3-demo-bucket1`. To remove a specific version of an object, you must be the bucket owner and you must use the version Id subresource. ``` aws s3api delete-object --bucket amzn-s3-demo-bucket1 --key test.txt --version-id versionID ``` For more information about `delete-object` see [https://docs.aws.amazon.com/cli/latest/reference/s3api/delete-object.html](https://docs.aws.amazon.com/cli/latest/reference/s3api/delete-object.html) in the *AWS CLI Command Reference*. For more information about deleting object versions, see the following topics: + [Working with delete markers](DeleteMarker.md) + [Removing delete markers to make an older version current](ManagingDelMarkers.md#RemDelMarker) + [Deleting an object from an MFA delete-enabled bucket](UsingMFADelete.md) # Working with delete markers A *delete marker* in Amazon S3 is a placeholder (or marker) for a versioned object that was specified in a simple `DELETE` request. A simple `DELETE` request is a request that doesn't specify a version ID. Because the object is in a versioning-enabled bucket, the object is not deleted. But the delete marker makes Amazon S3 behave as if the object is deleted. You can use an Amazon S3 API `DELETE` call on a delete marker. To do this, you must make the `DELETE` request by using an AWS Identity and Access Management (IAM) user or role with the appropriate permissions. A delete marker has a *key name* (or *key*) and version ID like any other object. However, a delete marker differs from other objects in the following ways: + A delete marker doesn't have data associated with it. + A delete marker isn't associated with an access control list (ACL) value. + If you issue a `GET` request for a delete marker, the `GET` request doesn't retrieve anything because a delete marker has no data. Specifically, when your `GET` request doesn't specify a `versionId`, you get a 404 (Not Found) error. Delete markers accrue a minimal charge for storage in Amazon S3. The storage size of a delete marker is equal to the size of the key name of the delete marker. A key name is a sequence of Unicode characters. The UTF-8 encoding for the key name adds 1‐4 bytes of storage to your bucket for each character in the name. Delete markers are stored in the S3 Standard storage class. If you want to find out how many delete markers you have and what storage class they're stored in, you can use Amazon S3 Storage Lens. For more information, see [Monitoring your storage activity and usage with Amazon S3 Storage Lens](storage_lens.md) and [Amazon S3 Storage Lens metrics glossary](storage_lens_metrics_glossary.md). For more information about key names, see [Naming Amazon S3 objects](object-keys.md). For information about deleting a delete marker, see [Managing delete markers](ManagingDelMarkers.md). Only Amazon S3 can create a delete marker, and it does so whenever you send a `DeleteObject` request on an object in a versioning-enabled or suspended bucket. The object specified in the `DELETE` request is not actually deleted. Instead, the delete marker becomes the current version of the object. The object's key name (or key) becomes the key of the delete marker. When you get an object without specifying a `versionId` in your request, if its current version is a delete marker, Amazon S3 responds with the following: + A 404 (Not Found) error + A response header, `x-amz-delete-marker: true` When you get an object by specifying a `versionId` in your request, if the specified version is a delete marker, Amazon S3 responds with the following: + A 405 (Method Not Allowed) error + A response header, `x-amz-delete-marker: true` + A response header, `Last-Modified: timestamp` (only when using the [HeadObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html) or [GetObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html) API operations) The `x-amz-delete-marker: true` response header tells you that the object accessed was a delete marker. This response header never returns `false`, because when the value is `false`, the current or specified version of the object is not a delete marker. The `Last-Modified` response header provides the creation time of the delete markers. The following figure shows how a `GetObject` API call on an object whose current version is a delete marker responds with a 404 (Not Found) error and the response header includes `x-amz-delete-marker: true`. ![\[Illustration that shows a GetObject call for a delete marker returning a 404 (Not Found) error.\]](http://docs.aws.amazon.com/AmazonS3/latest/userguide/images/versioning_DELETE_NoObjectFound.png) If you make a `GetObject` call on an object by specifying a `versionId` in your request, and if the specified version is a delete marker, Amazon S3 responds with a 405 (Method Not Allowed) error and the response headers include `x-amz-delete-marker: true` and `Last-Modified: timestamp`. ![\[Illustration that shows a GetObject call for a delete marker returning a 405 (Method Not Allowed) error.\]](http://docs.aws.amazon.com/AmazonS3/latest/userguide/images/versioning_DELETE_NoObjectFound_405.png) Even if overwritten, delete markers remain in your object versions. The only way to list delete markers (and other versions of an object) is by using a [https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectVersions.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectVersions.html) request. You can make this request in the AWS Management Console by listing your objects in an general purpose bucket and selecting **Show versions**. For more information, see [Listing objects in a versioning-enabled bucket](list-obj-version-enabled-bucket.md). The following figure shows that a [https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectsV2.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectsV2.html) or [https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjects.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjects.html) request doesn't return objects whose current version is a delete marker. ![\[Illustration that shows how a ListObjectsV2 or ListObjects call doesn't return any delete markers.\]](http://docs.aws.amazon.com/AmazonS3/latest/userguide/images/versioning_GETBucketwithDeleteMarkers.png) # Managing delete markers ## Configuring lifecycle to clean up expired delete markers automatically An expired object delete marker is one where all object versions are deleted and only a single delete marker remains. If the lifecycle configuration is set to delete current versions, or the `ExpiredObjectDeleteMarker` action is explicitly set, Amazon S3 removes the expired object’s delete marker. For an example, see [Removing expired object delete markers in a versioning-enabled bucket](lifecycle-configuration-examples.md#lifecycle-config-conceptual-ex7). ## Removing delete markers to make an older version current When you delete an object in a versioning-enabled bucket, all versions remain in the bucket, and Amazon S3 creates a delete marker for the object. To undelete the object, you must delete this delete marker. For more information about versioning and delete markers, see [Retaining multiple versions of objects with S3 Versioning](Versioning.md). To delete a delete marker permanently, you must include its version ID in a `DeleteObject versionId` request. The following figure shows how a `DeleteObject versionId` request permanently removes a delete marker. ![\[Illustration that shows a delete marker deletion using its version ID.\]](http://docs.aws.amazon.com/AmazonS3/latest/userguide/images/versioning_DELETE_deleteMarkerVersioned.png) The effect of removing the delete marker is that a simple `GET` request will now retrieve the current version ID (121212) of the object. **Note** If you use a `DeleteObject` request where the current version is a delete marker (without specifying the version ID of the delete marker), Amazon S3 does not delete the delete marker, but instead `PUTs` another delete marker. To delete a delete marker with a `NULL` version ID, you must pass the `NULL` as the version ID in the `DeleteObject` request. The following figure shows how a simple `DeleteObject` request made without a version ID where the current version is a delete marker, removes nothing, but instead adds an additional delete marker with a unique version ID (7498372). ![\[Illustration that shows a delete marker deletion using a NULL version ID.\]](http://docs.aws.amazon.com/AmazonS3/latest/userguide/images/versioning_DELETE_deleteMarker.png) ## Using the S3 console Use the following steps to recover deleted objects that are not folders from your S3 bucket, including objects that are within those folders. 1. Sign in to the AWS Management Console and open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/). 1. In the **Buckets** list, choose the name of the bucket that you want. 1. To see a list of the **versions** of the objects in the bucket, choose the **List versions** switch. You'll be able to see the delete markers for deleted objects. 1. To undelete an object, you must delete the delete marker. Select the check box next to the **delete marker** of the object to recover, and then choose **Delete**. 1. Confirm the deletion on the **Delete objects** page. 1. For **Permanently delete objects?** enter **permanently delete**. 1. Choose **Delete objects**. **Note** You can't use the Amazon S3 console to undelete folders. You must use the AWS CLI or SDK. For examples, see [ How can I retrieve an Amazon S3 object that was deleted in a versioning-enabled bucket?](https://aws.amazon.com/premiumsupport/knowledge-center/s3-undelete-configuration/) in the AWS Knowledge Center. ## Using the REST API **To permanently remove a delete marker** 1. Set `versionId` to the ID of the version to the delete marker you want to remove. 1. Send a `DELETE Object versionId` request. **Example — Removing a delete marker** The following example removes the delete marker for `photo.gif` version 4857693. ``` 1. DELETE /photo.gif?versionId=4857693 HTTP/1.1 2. Host: bucket.s3.amazonaws.com 3. Date: Wed, 28 Oct 2009 22:32:00 GMT 4. Authorization: AWS AKIAIOSFODNN7EXAMPLE:0RQf4/cRonhpaBX5sCYVf1bNRuU= ``` When you delete a delete marker, Amazon S3 includes the following in the response. ``` 1. 204 NoContent 2. x-amz-version-id: versionID 3. x-amz-delete-marker: true ``` ## Using the AWS SDKs For information about using other AWS SDKs, see the [AWSDeveloper Center](https://aws.amazon.com/code/). ------ #### [ Python ] The following Python code example demonstrates how to remove a delete marker from an object and thus makes the most recent non-current version, the current version of the object. ``` def revive_object(bucket, object_key): """ Revives a versioned object that was deleted by removing the object's active delete marker. A versioned object presents as deleted when its latest version is a delete marker. By removing the delete marker, we make the previous version the latest version and the object then presents as *not* deleted. Usage is shown in the usage_demo_single_object function at the end of this module. :param bucket: The bucket that contains the object. :param object_key: The object to revive. """ # Get the latest version for the object. response = s3.meta.client.list_object_versions( Bucket=bucket.name, Prefix=object_key, MaxKeys=1 ) if "DeleteMarkers" in response: latest_version = response["DeleteMarkers"][0] if latest_version["IsLatest"]: logger.info( "Object %s was indeed deleted on %s. Let's revive it.", object_key, latest_version["LastModified"], ) obj = bucket.Object(object_key) obj.Version(latest_version["VersionId"]).delete() logger.info( "Revived %s, active version is now %s with body '%s'", object_key, obj.version_id, obj.get()["Body"].read(), ) else: logger.warning( "Delete marker is not the latest version for %s!", object_key ) elif "Versions" in response: logger.warning("Got an active version for %s, nothing to do.", object_key) else: logger.error("Couldn't get any version info for %s.", object_key) ``` ------ # Deleting an object from an MFA delete-enabled bucket When you configure MFA delete, only the root user can permanently delete object versions or change the versioning configuration on your S3 bucket. You must use an MFA device to authenticate the root user to perform the delete action. If a bucket's versioning configuration is MFA delete enabled, the bucket owner must include the `x-amz-mfa` request header in requests to permanently delete an object version or change the versioning state of the bucket. Requests that include `x-amz-mfa` must use HTTPS. The header's value is the concatenation of your authentication device's serial number, a space, and the authentication code displayed on it. If you don't include this request header, the request fails. When using the AWS CLI include the same information as the value of the `mfa` parameter. For more information about authentication devices, see [Multi-factor Authentication](https://aws.amazon.com/iam/details/mfa/). For more information about enabling MFA delete, see [Configuring MFA delete](MultiFactorAuthenticationDelete.md). **Note** Deleting an object in a versioning-enabled bucket that is MFA delete enabled is not available through the AWS Management Console. ## Using the AWS CLI To delete an object in a versioning-enabled bucket that is MFA delete enabled, use the following command. When you use the following example command, replace the `user input placeholders` with your own information. ``` aws s3api delete-object --bucket amzn-s3-demo-bucket --key OBJECT-KEY --version-id "VERSION ID" --mfa "MFA_DEVICE_SERIAL_NUMBER MFA_DEVICE_CODE" ``` ## Using the REST API The following example deletes `my-image.jpg` (with the specified version), which is in a bucket configured with MFA delete enabled. For more information, see [https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectDELETE.html](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectDELETE.html) in the Amazon Simple Storage Service API Reference ``` 1. DELETE /my-image.jpg?versionId=3HL4kqCxf3vjVBH40Nrjfkd HTTPS/1.1 2. Host: bucketName.s3.amazonaws.com 3. x-amz-mfa: 20899872 301749 4. Date: Wed, 28 Oct 2009 22:32:00 GMT 5. Authorization: AWS AKIAIOSFODNN7EXAMPLE:0RQf4/cRonhpaBX5sCYVf1bNRuU= ``` # Configuring versioned object permissions Permissions for objects in Amazon S3 are set at the version level. Each version has its own object owner. The AWS account that creates the object version is the owner. So, you can set different permissions for different versions of the same object. To do so, you must specify the version ID of the object whose permissions you want to set in a `PUT Object versionId acl` request. For a detailed description and instructions on using ACLs, see [Identity and Access Management for Amazon S3](security-iam.md). **Example — Setting permissions for an object version** The following request sets the permission of the grantee with canonical user ID *b4bf1b36f9716f094c3079dcf5ac9982d4f2847de46204d47448bc557fb5ac2a*, to `FULL_CONTROL` on the key, `my-image.jpg`, version ID, `3HL4kqtJvjVBH40Nrjfkd`. ``` 1. PUT /my-image.jpg?acl&versionId=3HL4kqtJvjVBH40Nrjfkd HTTP/1.1 2. Host: bucket.s3.amazonaws.com 3. Date: Wed, 28 Oct 2009 22:32:00 GMT 4. Authorization: AWS AKIAIOSFODNN7EXAMPLE:0RQf4/cRonhpaBX5sCYVf1bNRuU= 5. Content-Length: 124 6. 7. 8. 9. 75cc57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a 10. 11. 12. 13. 14. a9a7b886d6fd24a52fe8ca5bef65f89a64e0193f23000e241bf9b1c61be666e9 15. 16. FULL_CONTROL 17. 18. 19. ``` Likewise, to get the permissions of a specific object version, you must specify its version ID in a `GET Object versionId acl` request. You need to include the version ID because, by default, `GET Object acl` returns the permissions of the current version of the object. **Example — Retrieving the permissions for a specified object version** In the following example, Amazon S3 returns the permissions for the key, `my-image.jpg`, version ID, `DVBH40Nr8X8gUMLUo`. ``` 1. GET /my-image.jpg?versionId=DVBH40Nr8X8gUMLUo&acl HTTP/1.1 2. Host: bucket.s3.amazonaws.com 3. Date: Wed, 28 Oct 2009 22:32:00 GMT 4. Authorization: AWS AKIAIOSFODNN7EXAMPLE:0RQf4/cRonhpaBX5sCYVf1bNRuU ``` For more information, see [https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectGETacl.html](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectGETacl.html) in the *Amazon Simple Storage Service API Reference*.