AWS CLI: S3 `ls` – List Buckets & Objects (Contents)

Amazon Simple Storage Service (S3) stores data as objects within resources called buckets.

Each Amazon S3 object consist of a key (file name), data and metadata that describes this object.

Amazon S3 lets you store and retrieve data via API over HTTPS using the AWS command-line interface (CLI).

In this note i will show how to list Amazon S3 buckets and objects from the AWS CLI using the aws s3 ls command.

List AWS S3 Buckets

List all S3 buckets owned by the current user:

$ aws s3 ls

List S3 buckets available for the named profile:

$ aws --profile <profile_name> s3 ls

Default Profile: Whenever you want to specify the AWS profile to use, you have to invoke the AWS command with the --profile parameter or you can set the environment variable AWS_DEFAULT_PROFILE. If this variable is not defined or the --profile parameter is not set, the AWS CLI will use the profile named default.

List Objects in AWS S3 Bucket

List the objects in S3 bucket:

$ aws s3 ls s3://<bucket_name>

List the objects in the specified “folder” on S3 bucket:

$ aws s3 ls s3://<bucket_name>/<folder_name>/

Folders in S3 Bucket: Folders don’t actually exist within S3 buckets. Amazon S3 has a flat structure instead of a filesystem-like hierarchy. The illusion of nested files inside folders inside the other folders is caused by the naming of the files like: dirA/dirB/file.

List all of the objects in S3 bucket, including all files in all “folders”, with their size in human-readable format and a summary in the end (number of objects and the total size):

$ aws s3 ls --recursive --summarize --human-readable s3://<bucket_name>

With the similar query you can also list all the objects under the specified “folder” only:

$ aws s3 ls --recursive --summarize --human-readable s3://<bucket_name>/<folder_name>/

Note: The trailing slash after the “folder” name in the examples above is mandatory.