Nov 18, 20266 min read

How to Run SQS Locally for Development and Tests

Run an SQS-compatible queue on your laptop with ElasticMQ, Floci or LocalStack, wire the AWS SDK to it, and see where a local queue stops matching production SQS.

Illustration for How to Run SQS Locally for Development and Tests

SQS is the queue most AWS backends reach for first, and it is also the piece that makes local development awkward: the worker needs a queue to poll, the API needs a queue to send to, and the actual queue lives in an AWS account behind IAM.

Teams end up sharing a dev queue, which means two developers' workers steal each other's messages, or they skip the queue locally and call the handler directly, which hides exactly the retry and visibility-timeout behavior that breaks in production.

This guide covers the local SQS servers that are worth running in 2026, the SDK and queue setup that keeps local and production on the same code path, and the gaps a local queue cannot cover.

Local SQS options at a glance

Encore Pub/SubElasticMQFlociLocalStack
What runs locallyIn-memory Pub/Sub under encore runSQS-compatible serverAWS emulatorAWS emulator
Default portNone to configure932445664566
Account or tokenNone for localNoneNoneLocalStack account and auth token
Queue creationFrom the topic and subscription in codeCLI, API or config fileCLI or APICLI or API
Dead-letter queuesCreated per subscription on deploySupportedSupportedSupported
Production targetSNS and SQS in your AWS account, or GCP Pub/SubReal SQS, configured separatelyReal SQS, configured separatelyReal SQS, configured separately

Wire the SDK to a local endpoint

The application side is identical for every SQS-compatible server: set the endpoint and dummy credentials when a local variable is present, and read the queue URL from configuration rather than building it from an account ID.

// queue.ts import { SQSClient, SendMessageCommand, ReceiveMessageCommand, DeleteMessageCommand } from "@aws-sdk/client-sqs"; const endpoint = process.env.SQS_ENDPOINT; // e.g. http://localhost:9324 export const sqs = new SQSClient({ region: process.env.AWS_REGION ?? "eu-central-1", ...(endpoint && { endpoint, credentials: { accessKeyId: "x", secretAccessKey: "x" } }), }); const QueueUrl = process.env.ORDERS_QUEUE_URL!; export async function enqueue(orderId: string) { await sqs.send(new SendMessageCommand({ QueueUrl, MessageBody: JSON.stringify({ orderId }) })); } export async function pollOnce(handle: (body: { orderId: string }) => Promise<void>) { const { Messages = [] } = await sqs.send(new ReceiveMessageCommand({ QueueUrl, MaxNumberOfMessages: 10, WaitTimeSeconds: 20, })); for (const m of Messages) { await handle(JSON.parse(m.Body!)); await sqs.send(new DeleteMessageCommand({ QueueUrl, ReceiptHandle: m.ReceiptHandle! })); } }

A message that throws in handle is not deleted, so it becomes visible again after the visibility timeout and is retried, which is the behavior you want to exercise locally. WaitTimeSeconds: 20 turns on long polling, which ElasticMQ, Floci and LocalStack all honor.

ElasticMQ

ElasticMQ is an SQS-compatible message queue from SoftwareMill that runs in memory, with optional persistence. It only does SQS, starts in well under a second as the native image, and supports FIFO queues, dead-letter queues and long polling. Queues can be created from the CLI or declared in a config file so they exist at startup.

~
$ docker run -d --name elasticmq -p 9324:9324 softwaremill/elasticmq-native$ aws --endpoint-url http://localhost:9324 sqs create-queue --queue-name orders{ "QueueUrl": "http://localhost:9324/000000000000/orders"}$ SQS_ENDPOINT=http://localhost:9324 ORDERS_QUEUE_URL=http://localhost:9324/000000000000/orders npm run worker

To test the poison-message path, create a second queue and attach it with a redrive policy (maxReceiveCount), the same attribute you set on real SQS. The SQS dead-letter queue guide covers the production side of that setting.

Best fit: apps that only need SQS locally and want the smallest, lightest container.

Floci

Floci is an MIT-licensed AWS emulator on port 4566 that needs no account or token. It covers SQS alongside S3, SNS and other services, so it is the better choice when the worker reads from SQS and writes to S3, or when an SNS topic fans out to the queue.

Best fit: apps that need SNS and S3 next to SQS and are moving off the LocalStack image.

LocalStack

LocalStack still has the broadest AWS coverage and the most examples, and its SQS emulation includes FIFO and DLQs. From the March 2026 release on, the image requires a LocalStack account and an auth token in every environment that pulls it, covered in LocalStack alternatives.

Best fit: teams already licensed for LocalStack across several services.

What a local queue does not reproduce

None of these servers enforce IAM, so a worker that runs fine locally can still fail with AccessDenied in production when its task role lacks sqs:ReceiveMessage or kms:Decrypt on an encrypted queue. Quotas, throttling, and the exact timing of redelivery also differ. The SQS developer guide remains the source of truth for visibility timeouts, message retention (4 days by default, up to 14) and FIFO throughput, so keep one integration test that runs against a real queue in a dev account.

Encore Pub/Sub under encore run

Encore

Encore brings infrastructure from code to the worker and the API, and a topic plus a subscription replaces the queue, the endpoint variable and the polling loop. Under encore run, Pub/Sub runs in memory on your machine, so every developer gets their own queue with no container. On deploy to your own AWS account, Encore provisions SNS and SQS with a dead-letter queue per subscription and provisions an IAM role for the service; on GCP it uses Google Cloud Pub/Sub.

Set up the app

Get started
brew install encoredev/tap/encore &&
encore app create
Copy

Run in your terminal to get started locally.

// orders/events.ts import { Topic, Subscription } from "encore.dev/pubsub"; import { SQLDatabase } from "encore.dev/storage/sqldb"; const db = new SQLDatabase("orders", { migrations: "./migrations" }); export interface OrderPlaced { orderId: string; } export const orderPlaced = new Topic<OrderPlaced>("order-placed", { deliveryGuarantee: "at-least-once", }); // Retried on error, then moved to the subscription's dead-letter queue. const _ = new Subscription(orderPlaced, "reserve-stock", { handler: async ({ orderId }) => { // Idempotent: a redelivered message finds the row and does nothing. await db.exec` INSERT INTO reservations (order_id) VALUES (${orderId}) ON CONFLICT (order_id) DO NOTHING`; }, });

An endpoint publishes with await orderPlaced.publish({ orderId }), and the local development dashboard shows the publish and the subscriber call in the same trace. A handler that throws is retried and then dead-lettered, as on SQS, so the handler still has to be idempotent. Encore is not an SQS emulator: code that calls SQS directly through the AWS SDK keeps using one of the servers above.

A coding agent working in this repository can add a new topic and subscriber in one change and see the messages flow under encore run, with no queue URL or endpoint variable to wire up.

Best fit: TypeScript or Go backends that want queue-driven workers locally and SNS and SQS in their own AWS account from the same code.

Which one to pick

If you only need SQS and want it fast, run ElasticMQ. If the app also uses S3 or SNS and you are moving off LocalStack, Floci is the closer swap, and LocalStack remains the broadest option if you already pay for it. If the queue exists to connect two parts of a TypeScript or Go backend, an Encore topic and subscription gives you a per-developer queue locally and SNS and SQS in your account without an endpoint switch.

Frequently asked questions

How do I run SQS locally?

Start an SQS-compatible server such as ElasticMQ (port 9324) or Floci or LocalStack (port 4566), create the queue with the AWS CLI against that endpoint, and set the SDK's endpoint and dummy credentials from an environment variable. If the queue is an Encore Pub/Sub topic and subscription, encore run runs them in memory and no endpoint is needed.

Is ElasticMQ the same as SQS?

No. ElasticMQ implements the SQS API, including FIFO queues, dead-letter queues and long polling, and is a good fit for local development and tests. It is not AWS, so IAM policies, KMS encryption, quotas and the exact redelivery timing are not reproduced, and you still need a test against real SQS for those.

Deploy to your cloud on AWS and Google Cloud
without managing infrastructure

Encore lets developers and agents define application infrastructure directly in code, then automatically provisions it from local development to production in your AWS or GCP account.

~/orders — claude
Claude Code
Claude Code v2.1.180Opus 5.5~/orders