Object versioning and lifecycle policies

By default, overwriting or deleting an object in Supabase Storage removes the previous data permanently. With object versioning enabled on a bucket, Storage keeps the previous version on every overwrite and soft-deletes objects instead of removing them, so you can recover from accidental deletes, bad uploads, and faulty scripts.

Key features

1. Per-bucket opt-in: Enable versioning only on the buckets that need it. Other buckets are unaffected.
2. Version history: Every overwrite creates a new version with a unique version ID. List, download, or restore any version.
3. Soft delete: Deleted objects are hidden from listings but stay recoverable until permanently deleted.
4. Restore: Recover a deleted object, or roll a file back to an earlier version.
5. Lifecycle policies: Expire noncurrent versions after a set number of days, or keep up to the 100 most recent per object.
6. Suspend versioning: Stop creating new versions without losing existing ones.
7. Dashboard and API: Manage versions from the file preview panel, supabase-js, or the Storage API.

Common use cases

• Recover files deleted by mistake from the dashboard or by application code
• Roll back an object replaced by an upsert or a bad upload
• Undo bulk changes made by a faulty script or scheduled job
• Keep a change history for user-uploaded documents and assets

Good to know

• Existing reads and listings return the current version, so no client changes are required.
• Versioning applies to changes made after it's enabled. Objects already in the bucket have no prior history.
• Retained versions count toward storage usage and are billed as regular storage. Use lifecycle policies to control cost.
• Retaining versions adds no egress. Only downloading a version does.