This topic describes how to run, version control, and configure the AWS CLI version 2 on Docker using either the official Amazon Elastic Container Registry Public (Amazon ECR Public) or Docker Hub image. For more information on how to use Docker, seeDocker's documentation.

Official images provide isolation, portability, and security that AWS directly supports and maintains. This enables you to use the AWS CLI version 2 in a container-based environment without having to manage the installation yourself.

Prerequisites

You must have Docker installed. For installation instructions, see theDocker website.

To verify your installation of Docker, run the following command and confirm there is an output.

$docker --versionDocker version 19.03.1

Deciding between Amazon ECR Public and Docker Hub

We recommend using Amazon ECR Public over Docker Hub for AWS CLI images. Docker Hub has stricter rate limiting for public consumers which can cause throttling issues. In addition, Amazon ECR Public replicates images in more than one region to provide strong availability and handle region outage issues.

For more information on Docker Hub rate limiting seeUnderstanding Docker Hub Rate Limiting on theDocker website.

Run the official AWS CLI version 2 images

The first time you use thedocker run command, the latest image is downloaded to your computer. Each subsequent use of thedocker run command runs from your local copy.

To run the AWS CLI version 2 Docker images, use thedocker run command.

Amazon ECR Public

The official AWS CLI version 2 Amazon ECR Public image is hosted on Amazon ECR Public in theaws-cli/aws-cli repository.

$docker run --rm -it public.ecr.aws/aws-cli/aws-clicommand

Docker Hub

The official AWS CLI version 2 Docker image is hosted on Docker Hub in theamazon/aws-cli repository.

$docker run --rm -it amazon/aws-clicommand

This is how the command functions:

For more information about thedocker run command, see theDocker reference guide.

Notes on interfaces and backwards compatibility of the official images

Use specific versions and tags

The official AWS CLI version 2 image has multiple versions you can use, starting with version2.0.6. To run a specific version of the AWS CLI version 2, append the appropriate tag to yourdocker run command. The first time you use thedocker run command with a tag, the latest image for that tag is downloaded to your computer. Each subsequent use of thedocker run command with that tag runs from your local copy.

You can use two types of tags:

Update to the latest official image

Because the latest image is downloaded to your computer only the first time you use thedocker run command, you need to manually pull an updated image. To manually update to the latest version, we recommend you pull thelatest tagged image. Pulling the image downloads the latest version to your computer.

Amazon ECR Public

$docker pull public.ecr.aws/aws-cli/aws-cli:latest

Docker Hub

$docker pull amazon/aws-cli:latest

Share host files, credentials, environment variables, and configuration

Because the AWS CLI version 2 is run in a container, by default the CLI can't access the host file system, which includes configuration and credentials. To share the host file system, credentials, and configuration to the container, mount the host system’s~/.aws directory to the container at/root/.aws with the-v flag to thedocker run command. This allows the AWS CLI version 2 running in the container to locate host file information.

Amazon ECR Public

Linux and macOS

$docker run --rm -it -v ~/.aws:/root/.aws public.ecr.aws/aws-cli/aws-clicommand

Windows Command Prompt

$docker run --rm -it -v %userprofile%\.aws:/root/.aws public.ecr.aws/aws-cli/aws-clicommand

Windows PowerShell

C:\>docker run --rm -it -v $env:userprofile\.aws:/root/.aws  public.ecr.aws/aws-cli/aws-clicommand

Docker Hub

Linux and macOS

$docker run --rm -it -v ~/.aws:/root/.aws amazon/aws-clicommand

Windows Command Prompt

$docker run --rm -it -v %userprofile%\.aws:/root/.aws amazon/aws-clicommand

Windows PowerShell

C:\>docker run --rm -it -v $env:userprofile\.aws:/root/.aws  amazon/aws-clicommand

For more information about the-v flag and mounting, see theDocker reference guide.

Example 1: Providing credentials and configuration

In this example, we're providing host credentials and configuration when running thes3 ls command to list your buckets in Amazon Simple Storage Service (Amazon S3). The below examples use the default location for AWS CLI credentials and configuration files, to use a different location, change the file path.

Amazon ECR Public

Linux and macOS

$docker run --rm -it -v~/.aws:/root/.aws public.ecr.aws/aws-cli/aws-cli s3 ls2020-03-25 00:30:48 aws-cli-docker-demo

Windows Command Prompt

$docker run --rm -it -v%userprofile%\.aws:/root/.aws public.ecr.aws/aws-cli/aws-cli s3 ls2020-03-25 00:30:48 aws-cli-docker-demo

Windows PowerShell

C:\>docker run --rm -it -v$env:userprofile\.aws:/root/.aws public.ecr.aws/aws-cli/aws-cli s3 ls

Docker Hub

Linux and macOS

$docker run --rm -it -v~/.aws:/root/.aws amazon/aws-cli s3 ls2020-03-25 00:30:48 aws-cli-docker-demo

Windows Command Prompt

$docker run --rm -it -v%userprofile%\.aws:/root/.aws amazon/aws-cli s3 ls2020-03-25 00:30:48 aws-cli-docker-demo

Windows PowerShell

C:\>docker run --rm -it -v$env:userprofile\.aws:/root/.aws amazon/aws-cli s3 ls

You can call specific system's environment variables using the-e flag. To use an environment variable, call it by name.

Amazon ECR Public

Linux and macOS

$docker run --rm -it -v ~/.aws:/root/.aws-e ENVVAR_NAME public.ecr.aws/aws-cli/aws-cli s3 ls2020-03-25 00:30:48 aws-cli-docker-demo

Windows Command Prompt

$docker run --rm -it -v %userprofile%\.aws:/root/.aws-e ENVVAR_NAME public.ecr.aws/aws-cli/aws-cli s3 ls2020-03-25 00:30:48 aws-cli-docker-demo

Windows PowerShell

C:\>docker run --rm -it -v $env:userprofile\.aws:/root/.aws-e ENVVAR_NAME public.ecr.aws/aws-cli/aws-cli s3 ls

Docker Hub

Linux and macOS

$docker run --rm -it -v ~/.aws:/root/.aws-e ENVVAR_NAME amazon/aws-cli s3 ls2020-03-25 00:30:48 aws-cli-docker-demo

Windows Command Prompt

$docker run --rm -it -v %userprofile%\.aws:/root/.aws-e ENVVAR_NAME amazon/aws-cli s3 ls2020-03-25 00:30:48 aws-cli-docker-demo

Windows PowerShell

C:\>docker run --rm -it -v $env:userprofile\.aws:/root/.aws-e ENVVAR_NAME amazon/aws-cli s3 ls

Example 2: Downloading an Amazon S3 file to your host system

For some AWS CLI version 2 commands, you can read files from the host system in the container or write files from the container to the host system.

In this example, we download theS3 objects3://aws-cli-docker-demo/hello to your local file system by mounting the current working directory to the container's/aws directory. By downloading thehello object to the container's/aws directory, the file is saved to the host system’s current working directory also.

Amazon ECR Public

Linux and macOS

$docker run --rm -it -v ~/.aws:/root/.aws -v $(pwd):/aws public.ecr.aws/aws-cli/aws-cli s3 cp s3://aws-cli-docker-demo/hello .download: s3://aws-cli-docker-demo/hello to ./hello

Windows Command Prompt

$docker run --rm -it -v %userprofile%\.aws:/root/.aws -v %cd%:/aws public.ecr.aws/aws-cli/aws-cli s3 cp s3://aws-cli-docker-demo/hello .download: s3://aws-cli-docker-demo/hello to ./hello

Windows PowerShell

C:\>docker run --rm -it -v $env:userprofile\.aws:/root/.aws -v $pwd\aws:/aws public.ecr.aws/aws-cli/aws-cli s3 cp s3://aws-cli-docker-demo/hello .

Docker Hub

Linux and macOS

$docker run --rm -it -v ~/.aws:/root/.aws -v $(pwd):/aws amazon/aws-cli s3 cp s3://aws-cli-docker-demo/hello .download: s3://aws-cli-docker-demo/hello to ./hello

Windows Command Prompt

$docker run --rm -it -v %userprofile%\.aws:/root/.aws -v %cd%:/aws amazon/aws-cli s3 cp s3://aws-cli-docker-demo/hello .download: s3://aws-cli-docker-demo/hello to ./hello

Windows PowerShell

C:\>docker run --rm -it -v $env:userprofile\.aws:/root/.aws -v $pwd\aws:/aws amazon/aws-cli s3 cp s3://aws-cli-docker-demo/hello .

To confirm the downloaded file exists in the local file system, run the following.

Linux and macOS

$cat helloHello from Docker!

Windows PowerShell

$type helloHello from Docker!

Example 3: Using your AWS_PROFILE environment variable

You can call specific system's environment variables using the-e flag. Call each environment variable you'd like to use. In this example, we're providing host credentials, configuration, and theAWS_PROFILE environment variable when running thes3 ls command to list your buckets in Amazon Simple Storage Service (Amazon S3).

Amazon ECR Public

Linux and macOS

$docker run --rm -it -v ~/.aws:/root/.aws-e AWS_PROFILE public.ecr.aws/aws-cli/aws-cli s3 ls2020-03-25 00:30:48 aws-cli-docker-demo

Windows Command Prompt

$docker run --rm -it -v %userprofile%\.aws:/root/.aws-e AWS_PROFILE public.ecr.aws/aws-cli/aws-cli s3 ls2020-03-25 00:30:48 aws-cli-docker-demo

Windows PowerShell

C:\>docker run --rm -it -v $env:userprofile\.aws:/root/.aws-e AWS_PROFILE public.ecr.aws/aws-cli/aws-cli s3 ls

Docker Hub

Linux and macOS

$docker run --rm -it -v ~/.aws:/root/.aws-e AWS_PROFILE amazon/aws-cli s3 ls2020-03-25 00:30:48 aws-cli-docker-demo

Windows Command Prompt

$docker run --rm -it -v %userprofile%\.aws:/root/.aws-e AWS_PROFILE amazon/aws-cli s3 ls2020-03-25 00:30:48 aws-cli-docker-demo

Windows PowerShell

C:\>docker run --rm -it -v $env:userprofile\.aws:/root/.aws-e AWS_PROFILE amazon/aws-cli s3 ls

Shorten the docker run command

To shorten thedocker run command, we suggest you use your operating system's ability to create asymbolic link (symlink) oralias in Linux and macOS, ordoskey in Windows. To set theaws alias, you can run one of the following commands.

After setting your alias, you can run the AWS CLI version 2 from within a container as if it's installed on your host system.

$aws --versionaws-cli/2.27.41 Python/3.7.3 Linux/4.9.184-linuxkit botocore/2.4.5dev10

Thanks for letting us know we're doing a good job!

If you've got a moment, please tell us what we did right so we can do more of it.

Thanks for letting us know this page needs work. We're sorry we let you down.

If you've got a moment, please tell us how we can make the documentation better.