← R2 / r2 / buckets

Bucket locks

Bucket locks prevent the deletion and overwriting of objects in an R2 bucket for a specified period — or indefinitely. When enabled, bucket locks enforce retention policies on your objects, helping protect them from accidental or premature deletions.

Before getting started, you will need:

• An existing R2 bucket. If you do not already have an existing R2 bucket, refer to Create buckets.
• (API only) An API token with permissions to edit R2 bucket configuration.

1. In the Cloudflare dashboard, go to the R2 object storage page.

   Go to Overview ↗

2. Select the bucket you would like to add bucket lock rule to.

3. Switch to the Settings tab, then scroll down to the Bucket lock rules card.

4. Select Add rule and enter the rule name, prefix, and retention period.

5. Select Save changes.

1. Install npm ↗.
2. Install Wrangler, the Developer Platform CLI.
3. Log in to Wrangler with the wrangler login command.
4. Add a bucket lock rule to your bucket by running the r2 bucket lock add command.

npx wrangler r2 bucket lock add <BUCKET_NAME> [OPTIONS]

Alternatively, you can set the entire bucket lock configuration for a bucket from a JSON file using the r2 bucket lock set command.

npx wrangler r2 bucket lock set <BUCKET_NAME> --file <FILE_PATH>

The JSON file should be in the format of the request body of the put bucket lock configuration API.

For information about getting started with the Cloudflare API, refer to Make API calls. For information on required parameters and more examples of how to set bucket lock configuration, refer to the API documentation.

Below is an example of setting a bucket lock configuration (a collection of rules):

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/r2/buckets/<BUCKET_NAME>/lock" \
    -H "Authorization: Bearer <API_TOKEN>" \
    -H "Content-Type: application/json" \
    -d '{
        "rules": [
            {
                "id": "lock-logs-7d",
                "enabled": true,
                "prefix": "logs/",
                "condition": {
                    "type": "Age",
                    "maxAgeSeconds": 604800
                }
            },
            {
                "id": "lock-images-indefinite",
                "enabled": true,
                "prefix": "images/",
                "condition": {
                    "type": "Indefinite"
                }
            }
        ]
    }'

This request creates two rules:

• lock-logs-7d: Objects under the logs/ prefix are retained for 7 days (604800 seconds).
• lock-images-indefinite: Objects under the images/ prefix are locked indefinitely.

1. In the Cloudflare dashboard, go to the R2 object storage page.

   Go to Overview ↗

2. Select the bucket you would like to add bucket lock rule to.

3. Switch to the Settings tab, then scroll down to the Bucket lock rules card.

To list bucket lock rules, run the r2 bucket lock list command:

npx wrangler r2 bucket lock list <BUCKET_NAME>

For more information on required parameters and examples of how to get bucket lock rules, refer to the API documentation.

1. In the Cloudflare dashboard, go to the R2 object storage page.

   Go to Overview ↗

2. Select the bucket you would like to add bucket lock rule to.

3. Switch to the Settings tab, then scroll down to the Bucket lock rules card.

4. Locate the rule you want to remove, select the ... icon next to it, and then select Delete.

To remove a bucket lock rule, run the r2 bucket lock remove command:

npx wrangler r2 bucket lock remove <BUCKET_NAME> --id <RULE_ID>

To remove bucket lock rules via API, exclude them from your updated configuration and use the put bucket lock configuration API.

A bucket lock configuration can include up to 1,000 rules. Each rule specifies which objects it covers (via prefix) and how long those objects must remain locked. You can:

• Lock objects for a specific duration. For example, 90 days.
• Retain objects until a certain date. For example, until January 1, 2026.
• Keep objects locked indefinitely.

If multiple rules apply to the same prefix or object key, the strictest (longest) retention requirement takes precedence.

• Rules without prefix apply to all objects in the bucket.
• Rules apply to both new and existing objects in the bucket.
• Bucket lock rules take precedence over lifecycle rules. For example, if a lifecycle rule attempts to delete an object at 30 days but a bucket lock rule requires it be retained for 90 days, the object will not be deleted until the 90-day requirement is met.
• A bucket cannot be emptied while any bucket lock rules are configured. Remove all lock rules before emptying a bucket. Bucket lock rules also apply when deleting folders from the dashboard.