
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.
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_64sudo 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.rpmOn Amazon Linux 2, use
yum instead of dnf .Linux with Debian or Ubuntu
# amd64curl -fsSLo aws-emulator.deb https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator_amd64.debsudo apt-get install -y ./aws-emulator.deb
# arm64curl -fsSLo aws-emulator.deb https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator_arm64.debsudo apt-get install -y ./aws-emulator.debCheck the installation. The package goes to
/opt/aws-emulator/ and the command to /usr/bin/ .aws-emulator -vmacOS 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-minimalADD https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator-x86_64.rpm /tmp/aws-emulator.rpmRUN rpm -i /tmp/aws-emulator.rpm && rm /tmp/aws-emulator.rpm \ && mkdir -p /home/emulator && chown 1000 /home/emulatorUSER 1000ENV HOME=/home/emulatorEXPOSE 9297ENTRYPOINT ["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 offOn macOS (Docker):
mkdir -p ~/.aws/emulatorPORT=9297docker 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 offOn 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 = 9297docker 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 offAlways 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 Emulatorexport AWS_ENDPOINT_URL=https://127.0.0.1:9297export AWS_SHARED_CREDENTIALS_FILE=~/.aws/emulator/9297/emulator_credentialsexport AWS_CONFIG_FILE=~/.aws/emulator/9297/configexport AWS_CA_BUNDLE=~/.aws/emulator/9297/ca.pemexport AWS_EC2_METADATA_DISABLED=trueexport AWS_DISABLE_HOST_PREFIX_INJECTION=trueexport AWS_REGION=us-east-1export AWS_DEFAULT_REGION=us-east-1
# real credentials in environment variables win over the file: remove themunset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN AWS_PROFILELoad the file in the terminal you will work in:
source emulator-env.shOn 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 SilentlyContinue3. 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/healthNow the real test:
aws sts get-caller-identityIn 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.gitcd aws-emulator-notes-demoProject layout:
notes-demo/├── emulator-env.sh├── notes_app.py├── requirements.txt└── tests/ ├── conftest.py └── test_notes.pyrequirements.txt
boto3pytestInstall it in a virtual environment:
python3 -m venv .venvsource .venv/bin/activatepip install -r requirements.txtnotes_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 osimport sysimport uuidfrom pathlib import Path
import boto3import 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.fixturedef 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.shpytest -q testsThe 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.logThree 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.shsits in the same step aspytest. 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
configfile: it is rewritten on every start. If you need to, copy the file and pointAWS_CONFIG_FILEat 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-embeddedcrate), 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
- Test your applications against AWS locally with AWS Emulator , AWS News Blog, November 11, 2026
- AWS Emulator is now available , What's New with AWS
- Guilherme-Benfica/aws-emulator-notes-demo on GitHub , the companion code for this guide
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article