The AWS Emulator, ready to run in Docker.

mkdir -p ~/.aws/emulator
PORT=9297
docker run --rm --memory=2g --memory-swap=2g -p 127.0.0.1:$PORT:$PORT \
  --user "$(id -u):$(id -g)" \
  -e HOME="$HOME" -v "$HOME/.aws/emulator:$HOME/.aws/emulator" \
  ghcr.io/xsavikx/aws-emulator -p $PORTCopy

With rootless Docker, container root maps to your host user. Your own UID, or no --user, fails with Permission denied (os error 13).

mkdir -p ~/.aws/emulator
PORT=9297
docker run --rm --memory=2g --memory-swap=2g -p 127.0.0.1:$PORT:$PORT \
  --user 0:0 \
  -e HOME="$HOME" -v "$HOME/.aws/emulator:$HOME/.aws/emulator" \
  ghcr.io/xsavikx/aws-emulator -p $PORTCopy

New-Item -ItemType Directory -Force "$env:USERPROFILE\.aws\emulator"
$port = 9297
docker run --rm --memory=2g --memory-swap=2g -p "127.0.0.1:${port}:${port}" `
  -v "$env:USERPROFILE\.aws\emulator:/home/emulator/.aws/emulator" `
  ghcr.io/xsavikx/aws-emulator -p $portCopy

services:
  aws-emulator:
    image: ghcr.io/xsavikx/aws-emulator:latest
    command: ["-p", "9297"]
    user: "${UID_GID:-1000:1000}"
    environment:
      HOME: ${HOME}
    ports:
      - "127.0.0.1:9297:9297"
    volumes:
      - ${HOME}/.aws/emulator:${HOME}/.aws/emulator
    mem_limit: 2g
    memswap_limit: 2gCopy

Start it with UID_GID="$(id -u):$(id -g)" docker compose up.

export AWS_ENDPOINT_URL=https://127.0.0.1:9297
export AWS_SHARED_CREDENTIALS_FILE=~/.aws/emulator/9297/emulator_credentials
export AWS_CONFIG_FILE=~/.aws/emulator/9297/config
export AWS_CA_BUNDLE=~/.aws/emulator/9297/ca.pem
export AWS_EC2_METADATA_DISABLED=true
export AWS_DISABLE_HOST_PREFIX_INJECTION=true
export AWS_REGION=us-east-1 AWS_DEFAULT_REGION=us-east-1
unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN AWS_PROFILE

aws sts get-caller-identity   # "Account": "000000000000"Copy

$env:AWS_ENDPOINT_URL = "https://127.0.0.1:9297"
$env:AWS_SHARED_CREDENTIALS_FILE = "$env:USERPROFILE\.aws\emulator\9297\emulator_credentials"
$env:AWS_CONFIG_FILE = "$env:USERPROFILE\.aws\emulator\9297\config"
$env:AWS_CA_BUNDLE = "$env:USERPROFILE\.aws\emulator\9297\ca.pem"
$env:AWS_EC2_METADATA_DISABLED = "true"
$env:AWS_DISABLE_HOST_PREFIX_INJECTION = "true"
$env:AWS_REGION = "us-east-1"
$env:AWS_DEFAULT_REGION = "us-east-1"

aws sts get-caller-identityCopy

pytest + Boto3. Source and README.

import boto3
from botocore.config import Config

# Endpoint, keys, Region and CA come from the environment.
sts = boto3.client("sts")
s3 = boto3.client("s3", config=Config(s3={"addressing_style": "path"}))
sqs = boto3.client("sqs")Copy

examples/with-emulator.sh examples/python/run-tests.shCopy

Vitest + AWS SDK v3. Source and README.

import { S3Client } from "@aws-sdk/client-s3";
import { SQSClient } from "@aws-sdk/client-sqs";

// Endpoint, keys, Region and CA come from the environment.
const s3 = new S3Client({ forcePathStyle: true });
// The emulator returns queue URLs with the real AWS host.
// Keep SQS requests on AWS_ENDPOINT_URL:
const sqs = new SQSClient({ useQueueUrlAsEndpoint: false });Copy

examples/with-emulator.sh examples/typescript/run-tests.shCopy

JUnit 5 + AWS SDK 2.x. Source and README.

// Endpoint, keys and Region come from the environment.
// JAVA_TOOL_OPTIONS points to a truststore with the JDK CAs + emulator CA.
S3Client s3 = S3Client.builder().forcePathStyle(true).build();
SqsClient sqs = SqsClient.create();
DynamoDbClient dynamo = DynamoDbClient.create();Copy

examples/with-emulator.sh examples/java/run-tests.shCopy

go test + AWS SDK v2. Source and README.

// Endpoint, keys, Region and CA (AWS_CA_BUNDLE) come from the environment.
cfg, err := config.LoadDefaultConfig(ctx)
if err != nil {
	t.Fatal(err)
}
s3c := s3.NewFromConfig(cfg, func(o *s3.Options) { o.UsePathStyle = true })
sqsc := sqs.NewFromConfig(cfg)Copy

examples/with-emulator.sh examples/go/run-tests.shCopy

xUnit + AWS SDK for .NET v4. Source and README.

// SDK v4 reads AWS_ENDPOINT_URL. On Linux, .NET trusts the CA through
// SSL_CERT_FILE (system CAs + emulator CA).
var s3 = new AmazonS3Client(new AmazonS3Config { ForcePathStyle = true });
var sqs = new AmazonSQSClient();
var dynamo = new AmazonDynamoDBClient();Copy

examples/with-emulator.sh examples/dotnet/run-tests.shCopy

cargo test + Tokio. Source and README.

// Endpoint, keys and Region come from the environment. rustls trusts
// the CA through SSL_CERT_FILE (system CAs + emulator CA).
let config = aws_config::load_from_env().await; // feature "behavior-version-latest"
let s3 = aws_sdk_s3::Client::from_conf(
    aws_sdk_s3::config::Builder::from(&config).force_path_style(true).build(),
);
let sqs = aws_sdk_sqs::Client::new(&config);Copy

examples/with-emulator.sh examples/rust/run-tests.shCopy