Run DynamoDB in LocalStack with Docker Compose

Written by Rafal Wilinski
Published: November 20th, 2026
Run DynamoDB in LocalStack by starting its Docker container with a LocalStack auth token and pointing your AWS CLI or SDK at http://localhost:4566. LocalStack emulates multiple AWS services on your machine, so you can test a DynamoDB write and the Lambda function it triggers without deploying to AWS. The current image uses LocalStack's own Rust-based DynamoDB and Streams emulator by default. LocalStack installation · DynamoDB service coverage
Does LocalStack run DynamoDB Local internally?
Older versions used AWS's downloadable DynamoDB Local as their backend. The 2026.09.0 release, published October 2, 2026, made LocalStack's Rust-based engine the default on every plan. The deprecated DynamoDB Local backend is still available on paid plans via PROVIDER_OVERRIDE_DYNAMODB=legacy_pro. Requests go to the LocalStack gateway whichever backend is selected. Check the service coverage for the APIs you need before relying on a local test. LocalStack configuration · DynamoDB service coverage
LocalStack licensing and auth tokens in November 2026
On March 23, 2026, release 2026.03.0 consolidated the Community and Pro distributions. From that release onward, localstack/localstack and localstack/localstack-pro publish the same image, and startup requires a valid LocalStack auth token. Your token determines the features you can use. Older Community tags remain available as historical releases and miss subsequent fixes. March 2026 release announcement · Community migration notice · Auth token documentation
LocalStack lists Hobby as free for non-commercial use and Base, Ultimate and Enterprise as commercial subscriptions as of March 23, 2026. A verified GitHub Education student account can qualify for Student, and open-source projects can apply for sponsorship. The plan matrix lists DynamoDB, Streams, Lambda and CI testing on Hobby, subject to the non-commercial terms. Local state persistence is included on Base, Ultimate, Enterprise and Student. LocalStack plan matrix · LocalStack support plans
Use a personal Developer Token locally and a workspace CI Auth Token in automated pipelines. Pass either to the emulator as LOCALSTACK_AUTH_TOKEN. The AWS API clients below sign requests separately with the dummy values test and test. LocalStack auth tokens · LocalStack AWS credentials
Start LocalStack DynamoDB with Docker Compose
Save the following as compose.yaml in a demo directory. It pins the image to 2026.10.0, publishes the gateway on the host loopback address, and mounts the Docker socket so LocalStack can start Lambda runtime containers. You can omit the socket mount for DynamoDB-only development. LocalStack 2026.10.0 release · LocalStack Compose installation
Export LOCALSTACK_AUTH_TOKEN from your local secrets store or set it in an untracked .env file next to compose.yaml. Start Docker, then run docker compose up -d. Inspect startup with docker compose logs localstack if the API does not respond yet. The host endpoint is http://localhost:4566. If your application is another service in the same Compose project, use http://localstack:4566 so the hostname resolves to the LocalStack container. LocalStack networking
Connect with AWS CLI v2 or awslocal
Open a dedicated shell for the demo. Use the same region and credentials throughout so the CLI and both SDKs see the same tables. The function keeps the endpoint explicit on every request. AWS CLI endpoint configuration · LocalStack CLI configuration
For existing scripts that use awslocal, install the wrapper into a virtual environment alongside the already installed AWS CLI v2. LocalStack now deprecates awslocal in favor of lstk aws, and the older wrapper still works for these DynamoDB commands. LocalStack wrapper documentation
Create a table, put an item, query and scan
Create an on-demand Orders table with string keys customerId and orderId. Enable NEW_IMAGE so the same table works for the Lambda example below. Run this on a fresh instance, or use the startup hook later in the guide to create the table automatically. AWS CLI DynamoDB examples
Query targets a partition key and can narrow results by sort key. Scan reads across the table or index, so use it to inspect a small test table and use Query for customer order lookups. Both AWS APIs return paginated results. The AWS CLI paginates by default. In SDK code, use LastEvaluatedKey to continue when you need every result. To inspect the table visually, see the local DynamoDB GUI setup. AWS Query guide · AWS Scan guide · AWS CLI pagination
AWS SDK for JavaScript v3
Install @aws-sdk/client-dynamodb and @aws-sdk/lib-dynamodb with npm in your demo directory. Save this as orders.mjs and run node orders.mjs. The document client converts native JavaScript values to and from DynamoDB attribute values. AWS JavaScript DynamoDB guide
Python with boto3
If you skipped the awslocal example, create a virtual environment with python3 -m venv .venv. Install boto3 with .venv/bin/pip install boto3, save this as orders.py, and run .venv/bin/python orders.py. The low-level boto3 client uses DynamoDB's typed attribute values, just like the CLI command above. Boto3 session and endpoint reference If Python reports No module named boto3, check the interpreter running the script.
Persist DynamoDB data between restarts
If your plan includes local persistence, export ORDERS_PERSISTENCE=1 before starting the container and writing data. That sets PERSISTENCE=1 inside the container, and the named volume keeps /var/lib/localstack across container replacement. The default backend stores persistent DynamoDB state in the volume's state/dynamodb/ddb.sqlite file. Leave DYNAMODB_IN_MEMORY off. LocalStack persistence · DynamoDB storage
To verify persistence, start with that setting, create the table, write an order, then run docker compose restart localstack. Rerun the query after startup and check the order is still present. Keep the same Compose project and volume if you recreate the container. docker compose down -v deletes the named volume. On Hobby, use a startup hook to rebuild your test schema each time. Docker Compose down · LocalStack plans
Trigger a local Lambda from DynamoDB Streams
LocalStack supports DynamoDB Streams as a Lambda event source. Lambda polls the stream and hands a batch of records to the function. The example uses the stream on Orders and the Docker socket mount from the Compose file. See the DynamoDB Streams guide for stream view types and record structure. LocalStack Streams walkthrough · AWS Lambda event source mapping
Save this handler as orders_audit.py. It logs the keys for each change and the new image when one is present. AWS tutorial for processing DynamoDB records with Lambda
Package the handler, create an execution role, and attach the AWS-managed policy for reading stream records and writing function logs. Use the ARN returned by DescribeTable to wire up the trigger. TRIM_HORIZON starts at the oldest available record, so the first order may appear in the logs alongside the new test write. AWS Lambda execution role policy · AWS Lambda supported runtimes
Look for order-101 with aws_local logs tail /aws/lambda/orders-audit --since 10m. If the log group is missing immediately after the write, give the mapping time to start and poll, then rerun the command. Use aws_local lambda list-event-source-mappings --function-name orders-audit to check the mapping state. AWS Lambda function logs
Create tables on startup with a ready hook
Mount a Python script in LocalStack's ready.d directory to create the same schema on each clean start. The hook catches ResourceInUseException so restarting with a persisted Orders table preserves it. LocalStack initialization hooks · AWS CreateTable reference
Add the following line under services.localstack.volumes in compose.yaml, then run chmod +x init-orders.py and docker compose up -d. Check http://localhost:4566/_localstack/init/ready and look for the script's SUCCESSFUL state before running tests. LocalStack init hook status
If your project already manages tables as infrastructure as code, run the existing Terraform apply or CDK deploy after LocalStack is ready. The older tflocal and cdklocal wrappers are deprecated. LocalStack documents lstk terraform and lstk cdk as their replacements. LocalStack Terraform setup · LocalStack CDK setup
LocalStack vs. DynamoDB Local vs. a real AWS dev account
| Option | Fidelity | Features | Cost | CI use |
|---|---|---|---|---|
| LocalStack | Emulates AWS APIs with documented coverage and behavioral gaps | DynamoDB, Streams, local Lambda event source mappings, persistence on eligible plans | Free Hobby for non-commercial use, paid commercial plans | Test supported cross-service flows using a CI Auth Token |
| DynamoDB Local | AWS's downloadable emulator. It ignores provisioned throughput and runs without table partitioning | DynamoDB APIs and local Streams support. Lambda execution needs a separate runtime | Free download | Test data access and schema with a disposable database |
| AWS dev account | Runs actual AWS services under the account's IAM policies and quotas | Managed DynamoDB, Streams, Lambda and AWS operational features | AWS service pricing applies | Test deployed IAM, event delivery and managed-service behavior |
Use DynamoDB Local for table and query tests, LocalStack for supported workflows spanning services, and a real AWS account for checks that depend on managed-service behavior. AWS DynamoDB Local limitations · AWS DynamoDB Local downloads · AWS DynamoDB pricing · LocalStack service coverage
Run a DynamoDB smoke test in GitHub Actions
Save this workflow as .github/workflows/localstack-dynamodb.yml and add a workspace CI Auth Token to repository secrets as LOCALSTACK_AUTH_TOKEN. The Ubuntu job maps the service container's gateway to localhost, waits for a DynamoDB API response, writes a row, and verifies it with a query. The standard Ubuntu runner supplies the AWS CLI. LocalStack GitHub Actions guide · GitHub Actions service containers
Common LocalStack DynamoDB problems
| Symptom | What to check |
|---|---|
| Connection refused or timeout | Check docker compose ps and docker compose logs localstack. Confirm port 4566 is published. From a peer Compose service, use the service hostname. |
| LocalStack exits on startup | Check for a missing LOCALSTACK_AUTH_TOKEN, an expired license or a license that has yet to be assigned. |
ResourceNotFoundException | Check the endpoint, region and credentials with aws_local dynamodb list-tables. If using a ready hook, check the hook status. |
| Table data disappears | Check the plan's persistence entitlement, PERSISTENCE=1, the named volume and the DYNAMODB_IN_MEMORY setting. |
| Lambda receives no records | Check the Docker socket mount, LatestStreamArn, event source mapping state and function logs. Put a fresh item to produce another stream record. |
For a step-by-step diagnosis, see LocalStack DynamoDB not working. LocalStack auth troubleshooting · LocalStack endpoint networking · LocalStack Lambda support
Frequently Asked Questions
What is the LocalStack DynamoDB endpoint?
Does LocalStack still run DynamoDB Local internally?
Can I run the current LocalStack image without an auth token?
Can I keep LocalStack DynamoDB data after restarting Docker?
Can LocalStack trigger Lambda from DynamoDB Streams?
Dynobase is a Professional GUI Client for DynamoDB
Start your 7-day free trial today
Product Features
DynamoDB Tools
- SSH GUI Client
- Chat With Cloud
- MongoDB GUI Client
- AWS Cost Monitoring
- DynamoDB Query Builder
- DynamoDB Code Examples
- DynamoDB Node.js Queries
- DynamoDB JSON Converter
- DynamoDB UUID Generator
- DynamoDB Local Admin GUI
- DynamoDB Pricing Calculator
- DynamoDB Single-Table Design
- Best DynamoDB GUI Clients
- Dynobase vs DynoTable