What is a storage bucket?

In any object storage service, files live in a bucket. Before you upload your first photo or PDF, you create (or are given) a bucket and put everything inside it.

Understanding the bucket avoids three common mistakes: treating it like a folder, picking a name the service rejects, and mixing public and private files in the same place. The examples use Amazon S3 as the reference, because many other services follow the same model.

What is a bucket?#

A bucket is the container for the objects of an object storage service. Every object lives in exactly one bucket and is identified by the pair bucket + key.

A bucket does two jobs:

• Namespace: it gives the object its address. On S3, the object photos/cat.jpg in the bucket my-bucket in the us-west-2 Region lives at https://my-bucket.s3.us-west-2.amazonaws.com/photos/cat.jpg.
• Configuration point: access rules, object expiration, CORS, versioning, logging and replication are set on the bucket (or part of it), not file by file.

Is a bucket a folder?#

No, and the difference matters. A file system folder can contain other folders, have its own permissions and be moved. A bucket sits at the top, cannot be nested, and has no hierarchy underneath: the object namespace is flat.

What looks like a folder in a dashboard is a prefix, the beginning of the key. A prefix can be any length, within the 1,024-byte key limit on S3. The AWS documentation is explicit: prefixes look like directories, but they are not. To browse level by level, a listing uses a delimiter (usually /) and rolls up the keys that share a prefix.

What can I name a bucket?#

Each service sets its own rules. On S3, for general purpose buckets:

• 3 to 63 characters;
• only lowercase letters, numbers, periods (.) and hyphens (-);
• starts and ends with a letter or number;
• no two adjacent periods and not formatted as an IP address (like 192.168.5.4);
• unique across all accounts in the same AWS partition, in the global namespace.

In practice, this means:

• The name does not change. Once created, name and Region are fixed. Plan ahead.
• Do not put secrets in the name. It shows up in object URLs.
• Avoid periods. With periods in the name, the certificate for virtual-hosted-style addressing does not work over HTTPS. AWS recommends avoiding them, except for buckets used only for static website hosting.
• A deleted name may not come back. After you delete a bucket, another account can take the same name. To keep the name, empty the bucket instead of deleting it.
• Predictable names collide. If your application creates buckets by itself, append a random suffix (a UUID, for example). AWS also offers an account regional namespace, where only your account can use the name.

How do you organize files inside a bucket?#

Pick a key pattern and stick to it. This format tends to age well:

{type}/{year}/{month}/{id}-{name}.{ext}
avatars/2026/10/8f3a-cat.jpg
exports/2026/10/report-q3.csv

Good practices:

• One prefix per kind of content. It makes it easier to list files, apply expiration rules and grant access to just one part.
• An ID in the file name. It stops two users who upload photo.jpg from overwriting each other's file. Store only the key in your database.
• Split by policy, not by taste. If one set of files is public and another private, or one expires in 7 days and the other never does, use separate prefixes if the service applies rules per prefix, or separate buckets if it does not. See public vs private files.
• No sensitive data in the key. Keys appear in logs and URLs.

How do you create a bucket and list files by prefix?#

The example uses boto3, the AWS SDK for Python (pip install boto3). The endpoint, Region and credentials come from environment variables.

import os
import boto3

region = os.environ.get("S3_REGION", "us-east-1")  # on AWS, the bucket Region

s3 = boto3.client(
    "s3",
    endpoint_url=os.environ.get("S3_ENDPOINT"),  # omit to use AWS
    region_name=region,
    aws_access_key_id=os.environ["S3_ACCESS_KEY"],
    aws_secret_access_key=os.environ["S3_SECRET_KEY"],
)

bucket = os.environ["S3_BUCKET"]

if os.environ.get("CREATE_BUCKET"):
    extra = {} if region == "us-east-1" else {  # us-east-1 rejects a LocationConstraint
        "CreateBucketConfiguration": {"LocationConstraint": region}
    }
    s3.create_bucket(Bucket=bucket, **extra)

for key in ["photos/2026/cat.jpg", "photos/2026/dog.jpg", "docs/contract.pdf"]:
    s3.put_object(Bucket=bucket, Key=key, Body=b"example content")

resp = s3.list_objects_v2(Bucket=bucket, Delimiter="/")  # root level only
for p in resp.get("CommonPrefixes", []):
    print("folder:", p["Prefix"])  # photos/ and docs/

resp = s3.list_objects_v2(Bucket=bucket, Prefix="photos/2026/")  # one prefix only
for obj in resp.get("Contents", []):
    print(obj["Key"], obj["Size"])

Each list call returns up to 1,000 keys; for large buckets, use get_paginator("list_objects_v2"). The create_bucket call depends on a variable because many services create the bucket in the dashboard and hand you the name.

When should you create more than one bucket?#

A bucket is the boundary for rules. Create another one when you need:

• Different visibility: public images on one side, private exports on the other.
• A different Region: for latency or legal requirements. On S3, objects in a bucket never leave its Region unless you transfer them.
• Distinct lifecycles: logs that expire in 30 days and customer files that stay forever.
• Separate environments: development, staging and production, with no risk of deleting the wrong data.

For everything else, prefixes are enough. Avoid creating and deleting buckets on your application's critical path: AWS recommends doing it in a setup routine, not on every request.

Which terms show up alongside bucket?#

• Object: the file plus its metadata.
• Key: the unique name of the object inside the bucket.
• Prefix: the beginning of a key, used to simulate folders.
• Region: where the bucket physically lives.
• Bucket policy: a rule for who can do what.
• Lifecycle: expiration rules, covered in object lifecycle rules.

How to do this on Square Cloud#

Square Cloud Blob Storage is object storage with an S3-compatible API, so aws-cli, rclone, boto3 and the AWS SDKs work when pointed at https://s3-blob.squarecloud.app (region auto) with the S3 keys from the "S3 access" tab of the dashboard, as in the code above. You can also use the REST API or the web dashboard.

In Blob, each account has three fixed buckets: public, private and legacy (read-only). You cannot create named buckets, so leave CREATE_BUCKET unset in the example and use one of them.

Organizing by prefix works the same way: folders are key prefixes, and you set per-folder rules such as visibility, expiration, cache, maximum size, allowed extensions and automatic cleanup. On each object, you control expiration, Cache-Control and whether the file downloads or opens inline.

Each file can be up to 10 GB, and multipart is only required above 100 MB. Public files are served by a global CDN at the edge. Blob charges no egress or ingress fee, and every plan includes a quota from 5 GB to 250 GB.

Explore Blob Storage