AWS Builder Center
AWS Emulator in practice: test AWS on your machine, with no account and no cost

AWS Emulator in practice: test AWS on your machine, with no account and no cost

AWS launched AWS Emulator on November 11, 2026. This hands-on guide shows how to install it on Linux, macOS and Windows, point the AWS CLI at it, create S3 and DynamoDB resources, test a Python app with boto3 and pytest, and run it all in GitHub Actions, with no AWS account and no cost.

Senior Software Engineer .NET/AWS

Introduction

AWS Emulator, launched by AWS on November 11, 2026, answers AWS CLI and SDK calls on your own machine, with no AWS account and no service fee. In this guide you install the emulator, create S3 and DynamoDB resources with the CLI, write a Python test, and run it all in a CI pipeline.
The emulator is open source under the CC0 license and written in Rust. AWS says it was built and is maintained by AI agents, from the same API models that generate the SDKs. That is why, for the operations it supports, responses and errors have the same shape as on AWS.
If you are studying for a certification, it is a way to practice CLI commands and SDK calls without worrying about the bill. If you build software, it is a test loop measured in milliseconds, with no deployment.
All the code in this guide is on GitHub at  Guilherme-Benfica/aws-emulator-notes-demo . Its workflow runs the tests against AWS Emulator on every push: the first run reported account  000000000000  and  4 passed .

How it works

The emulator is a local program that serves an HTTPS endpoint for the AWS APIs. You set a few environment variables, and the CLI and SDKs send their calls to it without changing a single line of your code.



On startup, the emulator writes credentials, a config file and a certificate to  ~/.aws/emulator/9297/ , and the variables point the SDK at those files. Remove the variables and the same code talks to real AWS again.
There are two ways to use it:
  • Server mode: the emulator runs as a process (Linux) or a container (macOS and Windows) and serves any language. This guide uses this mode.
  • Embedded mode: only for Rust tests with the AWS SDK for Rust. The emulator runs inside the test process, with an isolated instance per test.

Prerequisites

You need one of these environments and three tools. You do not need an AWS account.
Item
Linux
macOS
Windows
How the emulator runs
Native package (RPM or Debian)
Docker
Docker
Processor
x86_64 or aarch64
Intel or Apple silicon
x86_64
AWS CLI v2
Yes
Yes
Yes
Python 3.10+ and pip (for the SDK part)
Yes
Yes
Yes
curl (for the health check)
Yes
Yes
Included in Windows 10+
Set aside about 2 GB of memory for the emulator. It uses about 160 MiB when idle and grows as you create resources, which all live in memory.

Step-by-step installation

On Linux the emulator is a native package; on macOS and Windows you build a Docker image from the official Dockerfile. AWS does not publish a ready-made image.

Linux with RPM (Amazon Linux 2023, Fedora, RHEL)

# x86_64
sudo dnf install -y https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator-x86_64.rpm

# aarch64 (Graviton, Arm)
sudo dnf install -y https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator-aarch64.rpm
On Amazon Linux 2, use  yum  instead of  dnf .

Linux with Debian or Ubuntu

# amd64
curl -fsSLo aws-emulator.deb https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator_amd64.deb
sudo apt-get install -y ./aws-emulator.deb

# arm64
curl -fsSLo aws-emulator.deb https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator_arm64.deb
sudo apt-get install -y ./aws-emulator.deb
Check the installation. The package goes to  /opt/aws-emulator/  and the command to  /usr/bin/ .
aws-emulator -v

macOS and Windows with Docker

Create an empty folder and, inside it, a file named  Dockerfile  with this content:
FROM public.ecr.aws/amazonlinux/amazonlinux:2023-minimal
ADD https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator-x86_64.rpm /tmp/aws-emulator.rpm
RUN rpm -i /tmp/aws-emulator.rpm && rm /tmp/aws-emulator.rpm \
&& mkdir -p /home/emulator && chown 1000 /home/emulator
USER 1000
ENV HOME=/home/emulator
EXPOSE 9297
ENTRYPOINT ["aws-emulator", "-b", "0.0.0.0"]
On a Mac with Apple silicon, replace  aws-emulator-x86_64.rpm  with  aws-emulator-aarch64.rpm  in the  ADD  line. Then build the image:
docker build -t aws-emulator .
The  -b 0.0.0.0  option makes the emulator listen inside the container. The  docker run  command in the next section is what limits access to your own machine.

First steps: start it and point the CLI at it

The emulator serves HTTPS on  127.0.0.1:9297  and writes credentials, config and a certificate to  ~/.aws/emulator/9297/ . You only need two terminals: one running the emulator and one with environment variables pointing at it.

1. Start the emulator (terminal 1)

On Linux:
aws-emulator --telemetry off
On macOS (Docker):
mkdir -p ~/.aws/emulator
PORT=9297
docker run --rm --memory=2g --memory-swap=2g -p 127.0.0.1:$PORT:$PORT \
-e HOME="$HOME" -v "$HOME/.aws/emulator:$HOME/.aws/emulator" \
aws-emulator -p $PORT --telemetry off
On Linux with Docker, add  --user "$(id -u):$(id -g)"  right after  docker run  so the files belong to your user. On Windows (PowerShell):
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" `
aws-emulator -p $port --telemetry off
Always use  127.0.0.1:port:port . The short form  port:port  exposes the emulator to your whole network. The  --telemetry off  flag is optional: telemetry is on by default and sends only anonymous usage data.

2. Point the CLI at the emulator (terminal 2)

Save these lines in a file named  emulator-env.sh :
# emulator-env.sh: points the AWS CLI and SDKs at the local AWS Emulator
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
export AWS_DEFAULT_REGION=us-east-1

# real credentials in environment variables win over the file: remove them
unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN AWS_PROFILE
Load the file in the terminal you will work in:
source emulator-env.sh
On Windows, the PowerShell equivalent is:
$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"
Remove-Item Env:AWS_ACCESS_KEY_ID, Env:AWS_SECRET_ACCESS_KEY, Env:AWS_SESSION_TOKEN, Env:AWS_PROFILE -ErrorAction SilentlyContinue

3. Check that you are talking to the emulator

The health check returns HTTP 200 with the body  ok :
curl --cacert ~/.aws/emulator/9297/ca.pem https://127.0.0.1:9297/__admin/health
Now the real test:
aws sts get-caller-identity
In the response,  Account  must be  000000000000  and  Arn  must be  arn:aws:iam::000000000000:user/emulator . If you see your real account number, the CLI is going to AWS: check the variables before you continue.

Hands-on with the CLI: S3 and DynamoDB

With terminal 2 pointed at the emulator, the commands are exactly the ones you would run on AWS. Nothing here is billed, because nothing leaves your machine.

Amazon S3: bucket, upload and listing

aws s3 mb s3://local-getting-started
# make_bucket: local-getting-started

echo "hello from the emulator" > hello.txt

aws s3 cp hello.txt s3://local-getting-started/
# upload: ./hello.txt to s3://local-getting-started/hello.txt

aws s3 ls s3://local-getting-started/
The last command lists the  hello.txt  you just uploaded.

Amazon DynamoDB: table, write and read

aws dynamodb create-table --table-name kiro-demo \
--attribute-definitions AttributeName=id,AttributeType=S \
--key-schema AttributeName=id,KeyType=HASH \
--billing-mode PAY_PER_REQUEST

aws dynamodb put-item --table-name kiro-demo \
--item '{"id": {"S": "item-1"}, "msg": {"S": "hello from kiro"}}'

aws dynamodb get-item --table-name kiro-demo --key '{"id": {"S": "item-1"}}'
The  get-item  call returns the item with  id  set to  item-1  and  msg  set to  hello from kiro .

Three things to know right away

  • Everything lives in memory. When you stop the emulator with Ctrl+C, it deletes the resources and the files in  ~/.aws/emulator/9297/ . Every start is a clean environment.
  • The keys and the certificate change on every start. Because the variables point at the file paths, you do not need to redo anything.
  • An operation the emulator does not implement yet returns HTTP 501 Not Implemented. It does not pretend the call worked.

Using an SDK: a Python app with tests

The SDK reads the same environment variables as the CLI, so your application code does not change at all to run against the emulator. Let's build a small app that stores a note's text in S3 and its metadata in DynamoDB, and test it with pytest.
Want to skip the typing? Clone the ready-made project and jump straight to Running it:
git clone https://github.com/Guilherme-Benfica/aws-emulator-notes-demo.git
cd aws-emulator-notes-demo
Project layout:
notes-demo/
├── emulator-env.sh
├── notes_app.py
├── requirements.txt
└── tests/
├── conftest.py
└── test_notes.py

requirements.txt

boto3
pytest
Install it in a virtual environment:
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

notes_app.py

Notice there is no endpoint and no credential in the code. It is the same code that runs on real AWS.
"""Sample app: stores the note text in S3 and its metadata in DynamoDB."""
import boto3

class NotesRepository:
def __init__(self, bucket: str, table: str):
self.bucket = bucket
self.table = table
# No endpoint or credentials in the code: the SDK reads the environment variables.
self.s3 = boto3.client("s3")
self.dynamodb = boto3.client("dynamodb")

def save(self, note_id: str, text: str) -> None:
body = text.encode("utf-8")
key = f"notes/{note_id}.txt"
self.s3.put_object(Bucket=self.bucket, Key=key, Body=body)
self.dynamodb.put_item(
TableName=self.table,
Item={
"id": {"S": note_id},
"s3_key": {"S": key},
"size": {"N": str(len(body))},
},
)

def load(self, note_id: str) -> str | None:
item = self.dynamodb.get_item(
TableName=self.table, Key={"id": {"S": note_id}}
).get("Item")
if item is None:
return None
obj = self.s3.get_object(Bucket=self.bucket, Key=item["s3_key"]["S"])
return obj["Body"].read().decode("utf-8")

tests/conftest.py

Two important things live here. The first is a safety guard: if the variables do not point at the emulator, the tests never start, so they can never create resources in your real account. The second creates a fresh bucket and table for each test.
import os
import sys
import uuid
from pathlib import Path

import boto3
import pytest

sys.path.insert(0, str(Path(__file__).resolve().parent.parent))

from notes_app import NotesRepository # noqa: E402

EMULATOR_ACCOUNT = "000000000000"

@pytest.fixture(scope="session", autouse=True)
def only_against_the_emulator():
"""Safety guard: abort if the tests are not talking to the emulator."""
endpoint = os.environ.get("AWS_ENDPOINT_URL", "")
if not endpoint.startswith("https://127.0.0.1"):
pytest.exit(
"AWS_ENDPOINT_URL does not point at the local emulator. Run: source emulator-env.sh",
returncode=1,
)
account = boto3.client("sts").get_caller_identity()["Account"]
if account != EMULATOR_ACCOUNT:
pytest.exit(
f"Account {account} is not the emulator account. Aborting so real AWS is never touched.",
returncode=1,
)

@pytest.fixture
def repo():
"""Creates a fresh bucket and table for each test."""
suffix = uuid.uuid4().hex[:8]
bucket = f"notes-{suffix}"
table = f"notes-{suffix}"

boto3.client("s3").create_bucket(Bucket=bucket)

dynamodb = boto3.client("dynamodb")
dynamodb.create_table(
TableName=table,
AttributeDefinitions=[{"AttributeName": "id", "AttributeType": "S"}],
KeySchema=[{"AttributeName": "id", "KeyType": "HASH"}],
BillingMode="PAY_PER_REQUEST",
)
dynamodb.get_waiter("table_exists").wait(TableName=table)

return NotesRepository(bucket, table)

tests/test_notes.py

def test_save_and_load_note(repo):
repo.save("n1", "Study for the SAA-C03")
assert repo.load("n1") == "Study for the SAA-C03"

def test_missing_note_returns_none(repo):
assert repo.load("does-not-exist") is None

def test_accents_are_preserved(repo):
repo.save("n2", "Unicode check: São Paulo, café, naïve")
assert repo.load("n2") == "Unicode check: São Paulo, café, naïve"

def test_overwrite_keeps_latest_text(repo):
repo.save("n3", "version 1")
repo.save("n3", "version 2")
assert repo.load("n3") == "version 2"

Running it

With the emulator running in terminal 1, in terminal 2:
source emulator-env.sh
pytest -q tests
The expected result is  4 passed . If you forget the  source , the guard aborts with a message telling you to load  emulator-env.sh .
Using another language? Boto3, the CLI and the SDK for Go only need  AWS_CA_BUNDLE . In Node.js, set  NODE_EXTRA_CA_CERTS  to the path of  ca.pem . In Java, point  JAVA_TOOL_OPTIONS  at the  truststore.p12  in the same folder. In .NET and Rust, set  SSL_CERT_FILE  to  ca.pem .

In CI/CD: GitHub Actions with no AWS credentials

The same project runs in a pipeline without any AWS secret: the job installs the emulator, waits for the health check, and runs pytest. Create the file  .github/workflows/tests.yml :
name: tests-with-aws-emulator

on:
push:
pull_request:

permissions:
contents: read

jobs:
test:
runs-on: ubuntu-24.04
steps:
- uses: actions/checkout@v4

- uses: actions/setup-python@v5
with:
python-version: "3.12"

- name: Install AWS Emulator
run: |
curl -fsSLo aws-emulator.deb https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator_amd64.deb
sudo apt-get install -y ./aws-emulator.deb
aws-emulator -v

- name: Start the emulator in the background
run: |
nohup aws-emulator --telemetry off > emulator.log 2>&1 &
for i in $(seq 30); do
curl -sf --cacert "$HOME/.aws/emulator/9297/ca.pem" https://127.0.0.1:9297/__admin/health && break
sleep 1
done
# fail the step if the emulator did not answer within 30 seconds
curl -sf --cacert "$HOME/.aws/emulator/9297/ca.pem" https://127.0.0.1:9297/__admin/health

- name: Install dependencies
run: pip install -r requirements.txt

- name: Run the tests against the emulator
run: |
source emulator-env.sh
aws sts get-caller-identity
pytest -q tests

- name: Show the emulator log if something fails
if: failure()
run: cat emulator.log
Three details of this workflow:
  • A process started with  &  stays alive for the next steps of the same job, so the emulator serves the tests and goes away with the runner.
  •  source emulator-env.sh  sits in the same step as  pytest . The documentation recommends this: if the endpoint is not set in the shell that runs the tests, the SDK calls real AWS with whatever credentials it finds.
  • The job has no AWS secret configured. Even if something goes wrong, there is no real credential to use.
You can see a real run of this workflow in the  Actions tab of the companion repository : the emulator installs in about 16 seconds and the four tests pass in about 12.

Limitations and good practices

The emulator speeds up development and testing, but it does not replace a final test on AWS. These are the limitations AWS itself documents, and what to do about each one.
Limitation
What it means
What to do
Does not evaluate IAM policies or resource-based policies the way AWS does
A call that AWS would deny can succeed on the emulator
Test permissions and security on AWS, never on the emulator
A single account ( 000000000000 ) with no separation by Region
No cross-account or cross-Region scenarios
For several Regions, run one emulator per Region, each on its own port ( -p )
Fidelity varies by service and operation
Not every operation behaves exactly like AWS
Check each release's fidelity scores and the tests in the aws-emulator-evaluation-suite repository
An unimplemented operation returns HTTP 501
The test fails clearly, not silently
Check the  issues/things-that-do-not-work/  folder and open an issue on GitHub
Everything is in memory and ephemeral
Stop the emulator and everything is gone
Use it to your advantage: every test run starts clean
Telemetry is on by default
Sends anonymous usage and error data, never your requests
Turn it off with  --telemetry off ,  EMULATOR_TELEMETRY=off  or in  config.toml 
S3 Control puts the account ID in the hostname
Those calls never reach the emulator
Always keep  127.0.0.1  (not  localhost ) in  AWS_ENDPOINT_URL 
Three good practices for any project:
  • Keep the guard in  conftest.py . It costs a few lines and stops a test from creating resources in your real account.
  • Do not add settings to the emulator's  config  file: it is rewritten on every start. If you need to, copy the file and point  AWS_CONFIG_FILE  at the copy.
  • Stop the emulator when your tests finish. AWS says it has not been tested for long-running use or load.

Conclusion and next steps

In a few minutes you installed AWS Emulator, created S3 and DynamoDB resources with the CLI, tested a Python app with pytest, and took it all to GitHub Actions, with no AWS account and no cost. The application code is identical to what runs in the cloud: only the environment variables change.
Next steps:
  • Run your own project against the emulator and check the release's fidelity scores for the services it uses.
  • If you write Rust, try embedded mode (the  aws-emulator-embedded  crate), which runs an isolated instance per test, with no endpoint and no certificate.
  • Using an AI agent in your editor? Install the official skill with  aws agent-toolkit add-skill --skill-name aws-emulator --region us-east-1  (requires AWS CLI 2.35.0 or later) and ask it to set up the emulator for you.
  • Found a difference from AWS? Open an issue in the repository with the service, the operation, the SDK and the expected response.

Sources

Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article