S3 Viewer
Open Viewer

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

TL;DR

Amazon S3 has no rename API — keys are immutable, by design. Cloudflare R2 follows the same S3 API and inherits the same constraint. To rename, you copy the object to the new key and delete the original. The AWS CLI does it with `aws s3 mv`; the SDKs do it with copyObject + deleteObject; S3 Viewer wraps the same pattern in a single right-click and preserves metadata and tags by default.

Steps

Step-by-step.

  1. 01

    In S3 Viewer: right-click → Rename

    Right-click any object in the file browser, choose Rename, type the new key. S3 Viewer issues a server-side CopyObject with MetadataDirective: 'COPY' and TaggingDirective: 'COPY', verifies the destination, then issues DeleteObject on the source — only confirming the rename when both succeed.
  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. Pass MetadataDirective: 'COPY' and TaggingDirective: 'COPY' or you silently lose metadata and tags — the SDK defaults replace them.
    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 need multipart copy

    A single CopyObject call fails above 5 GB. Switch to multipart copy: CreateMultipartUpload → UploadPartCopy for each part → CompleteMultipartUpload. S3 Viewer makes this switch automatically the moment the source object crosses 5 GB — you don't think about it.
  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.


Three things to handle: copies over 5 GB need multipart copy; metadata and tags are dropped unless you pass MetadataDirective: 'COPY' and TaggingDirective: 'COPY'; and the operation is not atomic, so a failure between copy and delete can leave you with two keys (or zero, if you deleted first).


S3 Viewer handles all three: it issues a multipart copy above the threshold, sets MetadataDirective and TaggingDirective to COPY by default, and only deletes the source after the destination write returns success. The same pattern works against Cloudflare R2 and any other S3-compatible provider.

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 right-click → Rename.

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?

By default CopyObject replaces metadata and drops tags — the SDK and CLI defaults are not preservation. To preserve metadata, set MetadataDirective to COPY. To preserve tags, set TaggingDirective to COPY. S3 Viewer sets both by default, so renaming doesn't silently strip your cache-control headers or object tags.

Can I rename a file in Cloudflare R2?

Same answer — R2 implements the S3 API, and Amazon S3's no-rename design carries over. Use the same copy + delete pattern. S3 Viewer's rename works identically against R2 buckets: one right-click, metadata preserved, multipart copy above 5 GB.

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', list every object under the prefix and copy + delete each one to the new prefix. S3 Viewer handles this when you rename a prefix in the UI; doing it by hand means doing it once per file.
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 for personal use.

Open ViewerStar on GitHub