LocalStack for AWS Is Moving to a Single Image. Here are Your Next Steps

Starting March 23, 2026, LocalStack for AWS will ship as a single, unified container image. Accessing the latest releases will require authenticated access using a LocalStack for AWS account and an auth token—including in CI. This post explains what’s changing, what your options are, and how to migrate from LocalStack Community usage to the unified image.

As we approach this consolidation, Community users generally have two paths:

Adopt authenticated usage to stay current on the latest releases
Pin to an older tagged release and accept the operational tradeoffs

The right choice depends on whether LocalStack is primarily used for individual development and experimentation, or as an operational dependency in your delivery pipeline (CI reliability, shared workflows, and parity expectations). The sections below outline what’s changing and what to account for operationally.

What’s changing in March 2026

Beginning on March 23, 2026, using the latest LocalStack for AWS releases will require:

A LocalStack for AWS account
An auth token (including for CI usage)

We will continue to deliver a Free plan to provide authenticated access to hobbyists and individual developers, as well as a Student Plan via GitHub’s Student Developer pack.

This shift enables a delivery model that supports:

Clearer control over how releases are accessed and consumed
A more consistent experience across local and CI environments
Faster iteration on parity improvements and platform reliability
Better visibility into product enhancements and other relevant updates

The common alternative: Pinning to an older Community tag

A likely reaction is: “We’ll just pin to an older image (for example, 4.12) and avoid the change.” That can be a valid short-term approach—especially if you’re mid-release or can’t adjust CI quickly. But the tradeoffs tend to show up over time.

1) Pinning increases parity drift over time

When you pin a version, you’re implicitly choosing:

No ongoing updates to LocalStack for AWS
Limited parity as AWS behavior evolves
A growing mismatch between what you test locally and what runs in AWS

At a small scale, this is an inconvenience. At team scale—especially with CI as a release gate—drift can turn into repeated debugging cycles and harder-to-explain staging/production differences.

2) You’ll accumulate security and compliance debt

Even if LocalStack is “just for testing,” pinned artifacts can become susceptible to:

Unpatched CVEs that are addressed in regularly updated releases
Frozen base images and dependencies

Many teams don’t feel this immediately—until they’re asked to justify why critical tooling is running on an outdated or unsupported build.

3) CI is typically where pinning becomes fragile first

CI automation is where drift and edge cases surface earliest. Over time, relying on an outdated instance can undermine:

Deterministic setup and repeatability
Secure credential handling (where applicable)
Consistent behavior at team scale

If your CI usage is significant, pinning can become a constraint as the surrounding ecosystem (AWS APIs, SDKs, IaC templates, and application behavior) continues to evolve.

4) “We’ll upgrade later” becomes a larger migration event

The longer you stay pinned, the more change you concentrate into a future moment:

Bigger version jumps
More behavior differences to reconcile all at once
More cross-team coordination (platform + DevOps + feature teams)

For teams that treat LocalStack as part of the delivery system, deferring upgrades often turns a small adjustment into ongoing maintenance.

Decision guide: Choose an approach based on how you use LocalStack

The right path depends on how deeply LocalStack is embedded in your workflow—whether you’re using it for personal experimentation or relying on it to support team-scale software delivery.

If you primarily use LocalStack locally (individuals)

Free plan + authenticated access is likely sufficient if:

You primarily develop locally and only need a limited set of AWS services.
You’re using LocalStack for non-commercial purposes
You’re comfortable with self-directed setup and changes over time

If LocalStack is embedded in CI or used by multiple developers

Consider our commercial offerings if you need:

A consistent, supported way to run the latest releases
Repeatable CI workflows with authenticated access
A predictable upgrade motion for team workflows

Our commercial solutions offer services and features beyond the OSS/free version, enhancing AWS parity and overall productivity for your team.

If LocalStack is rolling out broadly across a large team managing critical workloads

Consider Enterprise when you need:

Stronger governance and rollout controls
Deployment flexibility
Dedicated support / SLAs aligned to organizational requirements

Migration checklist (practical steps)

If you currently pull localstack/localstack:latest, use the steps below to move to authenticated usage.

1) Create a LocalStack account

From our Pricing page, review the available plans and create an account for the option that best matches your usage. Please refer to our recent pricing update for more details regarding the upcoming pricing plans.

2) Generate an auth token

Auth tokens identify your LocalStack account when you run LocalStack outside the web app—so LocalStack can authenticate you, apply the right entitlements, and enable access to paid/advanced features (where applicable).

Create the token in the LocalStack Web App (Tokens / Account settings) and treat it like a password: don’t commit it, and don’t print it to logs.

Optional example (docs-supported): localstack auth set-token YOUR_AUTH_TOKEN

3) Configure local environments to use the token

Set each developer’s own auth token in their local environment so LocalStack can authenticate and apply the correct feature access for that user. Tokens are user-specific—each developer should use their own token (not a shared team token).

The standard approach is to set your auth token using the LocalStack CLI, then start LocalStack as usual. The CLI will pick up the token and pass it through to the LocalStack container automatically:

localstack auth set-token <YOUR_AUTH_TOKEN>
localstack start

Fallback (env var)

If needed, you can also set the token via the LOCALSTACK_AUTH_TOKEN environment variable to ensure it’s available wherever LocalStack is started (e.g., terminal session, scripts):

export LOCALSTACK_AUTH_TOKEN="<your-auth-token>"

4) If you run in CI: Store the token in CI secrets and inject it as an env var

CI runs must be non-interactive, repeatable, and secure. Use a CI Auth Token (not a personal/developer Auth Token) for CI pipelines.

Store the CI Auth Token in your CI provider’s secret manager and inject it at runtime as LOCALSTACK_AUTH_TOKEN.

This avoids hardcoding credentials in workflow files, reduces accidental leakage in logs, and ensures pipelines can authenticate consistently across branches and runners.

What to do next

Individual developers

Create or sign in to a LocalStack account, then generate an auth token.
Switch to the consolidated LocalStack image and set LOCALSTACK_AUTH_TOKEN in your local environment.
Do this ahead of March 23, 2026, to avoid disruption when access to the latest releases requires authentication.

Teams using CI

Standardize on a registered account + auth token for automated runs (avoid per-developer tokens in shared pipelines).
Update pipelines to use the consolidated image and inject the CI auth token via CI secrets as LOCALSTACK_AUTH_TOKEN.
Validate in CI (for example, smoke-test key workflows/services) to confirm authenticated runs behave as expected and remain consistent over time.

Platform / enterprise rollouts

Align on the “registered account + consolidated image” rollout model (who owns the account, how tokens are issued/rotated, and where they’re stored).
Define governance and support requirements (access control, auditability, token lifecycle, escalation/support path), then roll out to teams using a repeatable template (Compose/Helm/CI examples).
Complete alignment and initial rollout planning before March 23, 2026, to avoid last-minute disruption.

Want the latest releases? Switch to authenticated usage with a registered account, adopt the consolidated image, and update your CI secrets before March 23, 2026.