Introduction

Amazon S3 does not have real directories. It stores objects in a flat namespace, and what looks like folders in the console is just object-key naming plus API parameters such as Prefix and Delimiter.

How S3 Simulates Directories

An S3 object key can contain slashes:

photos/2026/trip/image1.jpg
photos/2026/trip/image2.jpg
photos/2026/events/image3.jpg

S3 treats those keys as plain strings. The slash is meaningful only because tools and APIs use it as a visual separator.

That means a "directory listing" in S3 is really a filtered prefix query.

Listing Prefixes with the AWS CLI

To inspect objects under a path-like prefix:

aws s3 ls s3://my-bucket/photos/2026/

This produces a folder-style listing because the CLI is formatting keys for you. Under the hood, it is still querying objects by prefix.

If you want to see raw API-style information, use s3api:

1aws s3api list-objects-v2 \
2  --bucket my-bucket \
3  --prefix photos/2026/ \
4  --delimiter /

The --delimiter / option tells S3 to group deeper keys into CommonPrefixes, which is the closest thing S3 has to subdirectories.

Listing from Python with boto3

You can do the same thing programmatically:

1import boto3
2
3s3 = boto3.client("s3")
4
5response = s3.list_objects_v2(
6    Bucket="my-bucket",
7    Prefix="photos/2026/",
8    Delimiter="/"
9)
10
11print("Directories:")
12for item in response.get("CommonPrefixes", []):
13    print(item["Prefix"])
14
15print("Files:")
16for item in response.get("Contents", []):
17    print(item["Key"])

This separates "subdirectories" from objects directly under the prefix.

What Prefix and Delimiter Actually Do

These two parameters are the key to understanding S3 listings:

• 'Prefix limits results to keys that start with a given string'
• 'Delimiter asks S3 to collapse deeper matches into grouped prefixes'

Without a delimiter, S3 returns every matching object recursively. With Delimiter="/", you get one logical level at a time.

Empty Folders Are Not Real Objects

Another common surprise is that an empty folder does not really exist in S3 unless someone created a placeholder object such as photos/2026/. The S3 console may show a folder UI, but the underlying storage is still just keys.

That matters when applications expect filesystem behavior. If no object exists under a prefix, there is nothing for S3 to list.

This is also why deleting the last object under a prefix can make a "directory" disappear from the console. Nothing about the bucket hierarchy changed, because there was never a real directory entry to begin with.

Performance and Pagination

Large prefixes can require pagination. If you have many objects, keep following the continuation token:

1token = None
2
3while True:
4    kwargs = {"Bucket": "my-bucket", "Prefix": "photos/2026/"}
5    if token:
6        kwargs["ContinuationToken"] = token
7
8    response = s3.list_objects_v2(**kwargs)
9
10    for item in response.get("Contents", []):
11        print(item["Key"])
12
13    if not response.get("IsTruncated"):
14        break
15
16    token = response["NextContinuationToken"]

That pattern is important for real buckets with large result sets.

It is also a reminder that S3 listings are API operations over objects, not filesystem reads. The more keys you ask S3 to examine, the more important prefix design becomes for both latency and cost.

Common Pitfalls

• Assuming S3 directories are real filesystem directories.
• Forgetting Delimiter="/" and then wondering why the listing is recursive.
• Expecting an empty folder to exist when no placeholder object was created.
• Ignoring pagination on large prefixes and accidentally reading only the first page.

Summary

• S3 is flat object storage, not a hierarchical filesystem.
• Folder-like behavior comes from object-key prefixes plus the delimiter parameter.
• Use list_objects_v2 with Prefix and Delimiter="/" for one-level folder listings.
• The AWS CLI hides some of this complexity, but the underlying model is still key-based.
• Understanding prefixes is the main step to understanding S3 directory listings.