S3 Viewer
Open app

How to rename a file in S3 (and why it's tricky)

TL;DR

Renaming an S3 object requires copying it to a new key and removing the original. S3 Viewer does this server-side on every provider — AWS S3, Cloudflare R2, Backblaze B2, MinIO, and other S3-compatible endpoints — with no size cap: objects above 5 GB copy in multipart parts automatically. It refuses an occupied destination and rejects a source that changed since you reviewed it. Folder rename moves every object under the prefix the same way, and Copy to… and New folder use the same server-side copy.

Steps

Step-by-step.

  1. 01

    In S3 Viewer: open the ⋮ menu and choose Rename

    Open the ⋮ menu on the object's row and choose Rename, then type the new key. S3 Viewer issues a server-side CopyObject, which preserves the object's metadata, then issues DeleteObject on the source — only confirming the rename once both succeed. If an object already exists at the new key the rename is refused rather than overwriting it. The file must still match the one you reviewed: an ETag check catches a source that changed underneath you and refuses the rename instead of copying stale bytes. This works the same way on AWS S3, R2, B2, and every other connected provider.
  2. 02

    AWS CLI: aws s3 mv

    From a terminal, aws s3 mv performs a server-side copy then a delete. The bytes never leave AWS — there's no data transfer to your machine.
    aws s3 mv s3://my-bucket/old-key.png s3://my-bucket/new-key.png
  3. 03

    AWS SDK: copyObject + deleteObject

    If you're scripting it, run copyObject followed by deleteObject. Always verify the copy succeeded (HTTP 200 and matching ETag) before deleting the source. MetadataDirective and TaggingDirective both default to COPY, so metadata and tags carry over unless you explicitly ask for REPLACE.
    const copy = await s3.copyObject({
  CopySource: 'my-bucket/old.png',
  Bucket: 'my-bucket',
  Key: 'new.png',
  MetadataDirective: 'COPY',
  TaggingDirective: 'COPY',
});
await s3.deleteObject({ Bucket: 'my-bucket', Key: 'old.png' });
  4. 04

    Files over 5 GB copy in parts, automatically

    A single CopyObject call fails above 5 GB, so S3 Viewer switches to a multipart copy automatically — CreateMultipartUpload → UploadPartCopy for each part → CompleteMultipartUpload — then deletes the source. There is no size cap on rename in S3 Viewer. Scripting it yourself without the app, aws s3 mv does the same thing for you.
  5. 05

    Verify, then delete

    Confirm the new key exists with the right size and ETag before deleting the source. If you skip this and the copy silently fails, you can lose the file — there is no S3 undo.
  6. 06

    Update anything that referenced the old key

    CDN cache, presigned URLs, database rows, hard-coded asset paths. Renaming an object doesn't propagate — that's on you, regardless of which tool you used.

Under the hood

What's actually happening.

S3 is a flat key-value store. There is no RenameObject API call — keys are immutable once written, by design. Every “rename” in any S3 tool is the same two operations: CopyObject to write the bytes at the new key (server-side, no download), then DeleteObject on the old key.


Two things to handle: a single CopyObject fails above 5 GB, and the pair of calls is not atomic, so a failure between copy and delete can leave you with two keys (or zero, if you deleted first). Metadata and tags carry over on their own — MetadataDirective and TaggingDirective both default to COPY.


S3 Viewer checks that the source is unchanged before copying and deleting it, refuses the rename when something already exists at the target key (you get a conflict error rather than a silent overwrite), and switches to a multipart copy above 5 GB instead of rejecting the file — so there is no practical size limit. This works on AWS S3, R2, B2, and other connected providers, using whichever conditional headers each one enforces and a check immediately beforehand where it doesn't. Copy and delete are still separate calls, not one atomic operation: an external writer can still race them, and if the delete step fails after a successful copy, S3 Viewer says so rather than guessing — it never deletes a destination it just created to undo a partial rename.

FAQ

Common questions.

Can you rename a file in S3?

Not natively — Amazon S3 has no rename API and keys are immutable once written, by design. The standard pattern is to copy the object to the new key and delete the original. Every S3 tool does this under the hood, including the AWS CLI's aws s3 mv, the AWS SDKs' copyObject + deleteObject, and S3 Viewer's ⋮ menu → Rename, which works this way on AWS S3, R2, B2, and other S3-compatible endpoints alike.

How do I rename a file in S3 with the AWS CLI?

Run aws s3 mv s3://bucket/old-key s3://bucket/new-key. The CLI performs a server-side CopyObject followed by a DeleteObject. The bytes never download to your machine.

Does renaming an S3 file cost money?

Yes, a small amount. You pay for one CopyObject request and one DeleteObject request. The copy is server-side so there's no data transfer charge for same-region copies, but cross-region copies pay inter-region transfer rates.

What happens to metadata and tags when I rename an S3 object?

S3 Viewer preserves readable metadata, tags, permissions, and supported storage settings during rename, on every provider. A failed read of ACLs or tags never blocks the rename — it just means the new object gets the bucket's default settings instead. Only an object encrypted with a customer-supplied key (SSE-C) refuses rename, since S3 Viewer never has that key.

Can I rename a file in Cloudflare R2?

Yes. S3 Viewer renames R2 objects the same way it renames AWS S3 objects: a server-side copy followed by a delete. R2 doesn't offer a delete-time condition, so S3 Viewer checks the object is still the one you reviewed with a HEAD request immediately before deleting it, rather than trusting an R2-enforced condition the way it can on AWS.

How do I rename a folder in S3?

S3 has no folders — what looks like a folder is a shared key prefix. To rename a 'folder', every object under the prefix has to be copied and deleted to the new prefix. S3 Viewer's Rename folder action does exactly that: it lists every key under the old prefix and moves each one to the new prefix, showing progress and any per-object failures. From the CLI, aws s3 mv s3://bucket/old-prefix/ s3://bucket/new-prefix/ --recursive or rclone do the same thing.

Use S3 Viewer for this

Skip the CLI. Try it in the browser.

S3 Viewer turns the steps above into a single click. Open source, self-hostable, free.

Open appStar on GitHub