Skip to main content

🪣 Working with Buckets

Buckets are namespaces for your objects. You can create as many as you need.

s3 s3 mb s3://acme-uploads          # create
s3 s3 ls                            # list your buckets
s3 s3api head-bucket --bucket acme-uploads   # check existence
s3 s3 rb s3://acme-uploads          # delete (must be empty)
s3 s3 rb s3://acme-uploads --force  # delete including contents

Rules and behavior​

  • Names are globally unique across all Lighthouse S3 users, first come, first served — like Amazon S3. If a name is taken you'll get 409 BucketAlreadyExists.
  • Prefix your bucket names with something unique to you (acme-uploads, acme-backups) rather than generic names like data or backup.
  • One owner per bucket — the account that creates a bucket is the only one that can see or use it. Other accounts get 404 NoSuchBucket (names aren't probeable).
  • Deletion requires empty — 409 BucketNotEmpty otherwise; use --force to delete contents first.
  • Deleting your own bucket again / recreating an existing one returns the same errors Amazon S3 would (BucketAlreadyOwnedByYou), so tools that rely on those semantics work unchanged.

Organizing with prefixes​

S3 has no real folders — keys with / in them act like paths, and every listing tool understands them:

s3 s3 cp a.jpg s3://acme-uploads/2026/07/a.jpg
s3 s3 ls s3://acme-uploads/2026/       # shows "07/" as a prefix

ListObjectsV2 with prefix and delimiter is fully supported, including pagination for large buckets.