Prerequisites Before you start Create a bucket List buckets and objects Delete buckets Delete objects Move objects Copy objects Sync objects Frequently used options for s3 commands Resources

Using high-level (s3) commands in the AWS CLI

This topic describes some of the commands you can use to manage Amazon S3 buckets and objects using the aws s3 commands in the AWS CLI. For commands not covered in this topic and additional command examples, see the aws s3 commands in the AWS CLI Reference.

The high-level aws s3 commands simplify managing Amazon S3 objects. These commands enable you to manage the contents of Amazon S3 within itself and with local directories.

Prerequisites

To run the s3 commands, you need to:

Install and configure the AWS CLI. For more information, see Installing or updating to the latest version of the AWS CLI and Authentication and access credentials for the AWS CLI.
The profile that you use must have permissions that allow the AWS operations performed by the examples.
Understand these Amazon S3 terms:
- Bucket – A top-level Amazon S3 folder.
- Prefix – An Amazon S3 folder in a bucket.
- Object – Any item that's hosted in an Amazon S3 bucket.

Before you start

This section describes a few things to note before you use aws s3 commands.

Large object uploads

When you use aws s3 commands to upload large objects to an Amazon S3 bucket, the AWS CLI automatically performs a multipart upload. You can't resume a failed upload when using these aws s3 commands.

If the multipart upload fails due to a timeout, or if you manually canceled in the AWS CLI, the AWS CLI stops the upload and cleans up any files that were created. This process can take several minutes.

If the multipart upload or cleanup process is canceled by a kill command or system failure, the created files remain in the Amazon S3 bucket. To clean up the multipart upload, use the s3api abort-multipart-upload command.

File properties and tags in multipart copies

When you use the AWS CLI version 1 version of commands in the aws s3 namespace to copy a file from one Amazon S3 bucket location to another Amazon S3 bucket location, and that operation uses multipart copy, no file properties from the source object are copied to the destination object.

By default, the AWS CLI version 2 commands in the s3 namespace that perform multipart copies transfers all tags and the following set of properties from the source to the destination copy: content-type, content-language, content-encoding, content-disposition, cache-control, expires, and metadata.

This can result in additional AWS API calls to the Amazon S3 endpoint that would not have been made if you used AWS CLI version 1. These can include: HeadObject, GetObjectTagging, and PutObjectTagging.

If you need to change this default behavior in AWS CLI version 2 commands, use the --copy-props parameter to specify one of the following options:

default – The default value. Specifies that the copy includes all tags attached to the source object and the properties encompassed by the --metadata-directive parameter used for non-multipart copies: content-type, content-language, content-encoding, content-disposition, cache-control, expires, and metadata.
metadata-directive – Specifies that the copy includes only the properties that are encompassed by the --metadata-directive parameter used for non-multipart copies. It doesn't copy any tags.
none – Specifies that the copy includes none of the properties from the source object.

Create a bucket

Use the s3 mb command to make a bucket. Bucket names must be globally unique (unique across all of Amazon S3) and should be DNS compliant.

Bucket names can contain lowercase letters, numbers, hyphens, and periods. Bucket names can start and end only with a letter or number, and cannot contain a period next to a hyphen or another period.

Syntax


$ aws s3 mb <target> [--options]

The following example creates the s3://amzn-s3-demo-bucket bucket.


$ aws s3 mb s3://amzn-s3-demo-bucket

List buckets and objects

To list your buckets, folders, or objects, use the s3 ls command. Using the command without a target or options lists all buckets.

Syntax


$ aws s3 ls <target> [--options]

For a few common options to use with this command, and examples, see Frequently used options for s3 commands. For a complete list of available options, see s3 ls in the AWS CLI Command Reference.

The following example lists all of your Amazon S3 buckets.


$ aws s3 ls
2018-12-11 17:08:50 amzn-s3-demo-bucket1
2018-12-14 14:55:44 amzn-s3-demo-bucket2

The following command lists all objects and prefixes in a bucket. In this example output, the prefix example/ has one file named MyFile1.txt.


$ aws s3 ls s3://amzn-s3-demo-bucket
                           PRE example/
2018-12-04 19:05:48          3 MyFile1.txt

You can filter the output to a specific prefix by including it in the command. The following command lists the objects in bucket-name/example/ (that is, objects in bucket-name filtered by the prefix example/).


$ aws s3 ls s3://amzn-s3-demo-bucket/example/
2018-12-06 18:59:32          3 MyFile1.txt

To display only the buckets and objects in a specific region, use the --region options


$ aws s3 ls --region us-east-2
2018-12-06 18:59:32          3 MyFile1.txt

If you have a large list of buckets and objects, you can paginated the results using the --max-items or --page-size options. The --max-items option limits how many total buckets and objects are returned in a call and the --page-size option limits how many of those are listed on a page.


$ aws s3 ls --max-items 100 --page-size 10

For more information on pagination, see How to use the --page-size parameter and How to use the --max-items parameter.

Delete buckets

To delete a bucket, use the s3 rb command.

Syntax


$ aws s3 rb <target> [--options]

The following example removes the s3://amzn-s3-demo-bucket bucket.


$ aws s3 rb s3://amzn-s3-demo-bucket

By default, the bucket must be empty for the operation to succeed. To remove a bucket that's not empty, you need to include the --force option. If you're using a versioned bucket that contains previously deleted—but retained—objects, this command does not allow you to remove the bucket. You must first remove all of the content.

The following example deletes all objects and prefixes in the bucket, and then deletes the bucket.


$ aws s3 rb s3://amzn-s3-demo-bucket --force

Delete objects

To delete objects in a bucket or your local directory, use the s3 rm command.

Syntax


$ aws s3 rm  <target> [--options]

For a few common options to use with this command, and examples, see