How to use object lock
Object lock prevents objects from being deleted or overwritten for a defined period or indefinitely. It uses a write-once-read-many (WORM) model, commonly required for regulatory compliance and protection against ransomware or accidental deletion. Object lock can only be used in buckets with versioning enabled.
Overview
Object lock provides two mechanisms to protect your objects: retention and legal hold. You can enable either, or both, at the same time:
-
Retention allows you to apply a retention period and a retention mode to your objects, limiting the actions that users can perform on them:
- Compliance mode prevents users, including owners and users with administrative permissions, from deleting or overwriting objects during the specified retention period. The retention mode cannot be modified, and the retention period cannot be shortened.
- Governance mode prevents users without the necessary permissions from deleting or overwriting objects during the specified retention period. Authorized users can modify the retention settings and delete the targeted objects.
-
Legal hold is an independent ON/OFF switch that provides the same protection as retention but has no expiration date. It must be explicitly removed by a user with the appropriate permissions and is evaluated independently of any retention configuration.
Object lock is supported on Standard Multi-AZ, Standard One Zone, and Glacier storage classes.
Before you start
To complete the actions presented below, you must have:
- Owner status or IAM permissions allowing you to perform actions in the intended Organization
- Installed and configured the AWS CLI
Enable object lock on a bucket
You can enable object lock at bucket creation or on an existing bucket.
On a new bucket
On an existing bucket
Apply retention to a specific object
Object-level retention overrides the bucket default for that specific object.
Manage legal hold on an object
Legal hold is independent of retention settings and has no expiration date. It must be explicitly enabled and removed by a user with the necessary permissions.
Set a default retention policy on a bucket
A default retention policy applies automatically to every new object added to the bucket.
-
Run the following command to set a retention period of 365 days in compliance mode. Replace
my-locked-bucketwith your bucket name.aws s3api put-object-lock-configuration \ --bucket my-locked-bucket \ --object-lock-configuration '{ "ObjectLockEnabled": "Enabled", "Rule": { "DefaultRetention": { "Mode": "COMPLIANCE", "Days": 365 } } }'To use Governance mode with a duration in years, replace the
Ruleblock:"Rule": { "DefaultRetention": { "Mode": "GOVERNANCE", "Years": 5 } }No output is returned on success.
-
Run the following command to verify the configuration was applied correctly:
aws s3api get-object-lock-configuration \ --bucket my-locked-bucketAn output similar to the following displays:
{ "ObjectLockConfiguration": { "ObjectLockEnabled": "Enabled", "Rule": { "DefaultRetention": { "Mode": "COMPLIANCE", "Days": 365 } } } }
Technical reference
Object lock configuration tokens
ObjectLockConfiguration
Description: Root element of the lock configuration.
Required: Yes
ObjectLockEnabled
Description: Enables object lock on the bucket.
Type: String — Enabled
Required: Yes
Rule
Description: Default retention rule applied to every new object placed in the bucket.
Required: No
Mode
Description: Default retention mode for new objects.
Type: String — GOVERNANCE or COMPLIANCE
Required: Yes, if Rule is set
Days
Description: Default retention duration in days.
Type: Integer
Required: Use Days or Years, not both
Years
Description: Default retention duration in years.
Type: Integer
Required: Use Days or Years, not both
Object retention tokens
Mode
Description: Retention mode for the object.
Type: String — GOVERNANCE or COMPLIANCE
Required: Yes
RetainUntilDate
Description: Date on which the object retention expires.
Type: Timestamp (ISO 8601)
Required: Yes
Legal hold tokens
Status
Description: Enables or disables the legal hold on the object.
Type: String — ON or OFF
Required: Yes
Examples
Regulatory compliance bucket (compliance mode)
This example sets up a bucket for strict regulatory retention: all objects are locked in compliance mode for seven years and cannot be deleted or overwritten by any user until the period expires.
# Enable object lock on a new bucket
aws s3api create-bucket \
--bucket my-compliance-bucket \
--object-lock-enabled-for-bucket
# Set a default seven-year compliance retention on all new objects
aws s3api put-object-lock-configuration \
--bucket my-compliance-bucket \
--object-lock-configuration '{
"ObjectLockEnabled": "Enabled",
"Rule": {
"DefaultRetention": {
"Mode": "COMPLIANCE",
"Years": 7
}
}
}'Objects uploaded to my-compliance-bucket are automatically locked in compliance mode until seven years after their upload date. No user can shorten the retention period or delete objects before it expires.
Flexible protection bucket (governance mode + legal hold)
This example sets up a bucket with a default governance retention of 90 days, then places an additional legal hold on a specific object under active investigation.
# Enable object lock on an existing bucket
aws s3api put-object-lock-configuration \
--bucket my-governance-bucket \
--object-lock-configuration '{
"ObjectLockEnabled": "Enabled",
"Rule": {
"DefaultRetention": {
"Mode": "GOVERNANCE",
"Days": 90
}
}
}'
# Apply a legal hold to a specific object
aws s3api put-object-legal-hold \
--bucket my-governance-bucket \
--key audit/report-2026-05.pdf \
--legal-hold Status=ONObjects in my-governance-bucket are protected for 90 days under governance mode. Authorized users can override the retention if needed. The object audit/report-2026-05.pdf additionally has a legal hold, which blocks deletion regardless of the retention period and must be explicitly removed.