How to run AWS CLI in Docker

Workstations and CI runners sometimes need AWS CLI v2 for one job without changing the host package set. The official AWS CLI container image lets Docker provide that runtime while command arguments, mounted files, and the selected profile still decide which AWS account the request can touch.

AWS publishes the image in Amazon ECR Public as public.ecr.aws/aws-cli/aws-cli and also publishes amazon/aws-cli on Docker Hub. The container entrypoint is the aws executable, so arguments after the image name are passed to AWS CLI as if the command were installed on the host.

The container cannot read host files unless they are mounted. Mount the shared AWS CLI directory to /root/.aws when the command needs profiles or credentials, mount the current working directory to /aws when the command needs local files, and pin a full AWS CLI image tag for automation that must not move with latest.

1. Run the official AWS CLI image and print the bundled CLI version.

   $ docker run --rm public.ecr.aws/aws-cli/aws-cli:latest --version
   aws-cli/2.35.3 Python/3.14.5 Linux/6.10.14-linuxkit exe/x86_64

   Amazon ECR Public is the preferred registry for this image because AWS documents broader availability and fewer public pull-rate issues than Docker Hub. The exact aws-cli/2.x version changes when latest moves.

2. Inspect a mounted profile before making a live AWS request.

   $ docker run --rm \
     -v "$HOME/.aws:/root/.aws:ro" \
     public.ecr.aws/aws-cli/aws-cli:latest \
     configure list --profile operations
   NAME       : VALUE                    : TYPE             : LOCATION
   profile    : operations               : manual           : --profile
   access_key : ****************MPLE     : shared-credentials-file :
   secret_key : ****************EKEY     : shared-credentials-file :
   region     : us-east-1                : config-file      : ~/.aws/config

   The read-only mount lets the container use existing host profiles without writing new credentials or cache files back to the host. Remove :ro only for an intentional command that must update the shared AWS CLI directory.
   Related: How to find the AWS CLI config file location
   Related: How to find the AWS CLI shared credentials file location

3. Run a signed identity check from the container.

   $ docker run --rm \
     -v "$HOME/.aws:/root/.aws:ro" \
     public.ecr.aws/aws-cli/aws-cli:latest \
     sts get-caller-identity --profile operations --output json
   {
       "UserId": "AROAEXAMPLEID:cli-session",
       "Account": "123456789012",
       "Arn": "arn:aws:sts::123456789012:assumed-role/OperationsRole/cli-session"
   }

   The returned Account and Arn should match the account and role intended for the Docker-run command.
   Related: How to check the current caller identity in AWS CLI

4. Mount the current directory when the AWS CLI command needs local files.

   $ docker run --rm \
     -v "$HOME/.aws:/root/.aws:ro" \
     -v "$PWD:/aws" \
     public.ecr.aws/aws-cli/aws-cli:latest \
     s3 cp ./release.zip s3://company-artifacts/release.zip \
     --profile operations \
     --dryrun
   (dryrun) upload: release.zip to s3://company-artifacts/release.zip

   The official image uses /aws as its working directory. Mounting $PWD there makes relative paths such as ./release.zip point at files in the host directory where Docker was launched.

5. Pass a shell-selected profile into the container when the wrapper command should follow AWS_PROFILE.

   $ AWS_PROFILE=operations docker run --rm \
     -v "$HOME/.aws:/root/.aws:ro" \
     -e AWS_PROFILE \
     public.ecr.aws/aws-cli/aws-cli:latest \
     sts get-caller-identity --query Account --output text
   123456789012

   Do not pass raw AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, or AWS_SESSION_TOKEN into shared transcripts or screenshots. Mount an approved profile file or pass short-lived environment credentials only in a private shell.

6. Refresh the local latest image when the next run should use the current published build.

   $ docker pull public.ecr.aws/aws-cli/aws-cli:latest
   latest: Pulling from aws-cli/aws-cli
   ##### snipped #####
   Status: Downloaded newer image for public.ecr.aws/aws-cli/aws-cli:latest
   public.ecr.aws/aws-cli/aws-cli:latest

   Skip this refresh for pinned commands such as public.ecr.aws/aws-cli/aws-cli:2.35.3. Full version tags are the safer choice for release jobs because AWS does not guarantee backwards compatibility for latest.