`localstack/localstack:latest` will require auth token from March 23 — LocalStack module docs & examples need updating

[HarshCasper]

Hey folks 👋

I'm Harsh from the LocalStack team. Wanted to flag an upcoming change that will directly affect users of the LocalStack module in this library.

What's changing: Starting March 23, 2026, localstack/localstack:latest on Docker Hub will consolidate into a single unified image that requires authentication via a LOCALSTACK_AUTH_TOKEN. The free Community image, as it exists today, will no longer be available under that tag without an auth token set.

What this means for this repo:

The LocalStackContainer in modules/localstack pulls localstack/localstack by default to spin up the container during tests. Any user who instantiates LocalStackContainer after March 23 without a LOCALSTACK_AUTH_TOKEN set will hit an authentication error and their tests will fail immediately.

The places most likely to need updating:

• The LocalStack module docs and any related examples in modules/localstack, which don't currently mention auth token setup as a prerequisite
• The LocalStackContainer class itself, where passing LOCALSTACK_AUTH_TOKEN as an environment variable should be documented or facilitated
• The CI/CD pipeline (.github/workflows/ci-community.yml) if it runs LocalStack-based tests without an auth token

What users will need to do:

1. Sign up for a free LocalStack account at [localstack.cloud](https://localstack.cloud/)
2. Generate an auth token from the LocalStack Web App
3. Set LOCALSTACK_AUTH_TOKEN as an environment variable when starting the container

With testcontainers-python, this would look like:

import os
from testcontainers.localstack import LocalStackContainer

with LocalStackContainer() \
        .with_env("LOCALSTACK_AUTH_TOKEN", os.environ.get("LOCALSTACK_AUTH_TOKEN", "")) as localstack:
    # your test code here
    pass

The good news: A free tier is staying — no one has to pay. CI credits are now unlimited on all plans, including free, and open-source projects like this one can apply for free access to paid plans.

Full details in our announcements:

• https://blog.localstack.cloud/the-road-ahead-for-localstack/
• https://blog.localstack.cloud/localstack-single-image-next-steps/
• https://blog.localstack.cloud/2026-upcoming-pricing-changes/

Happy to help with any doc updates, review PRs, or answer questions. Let us know if there's anything we can do to make this easier — and thanks for maintaining the LocalStack module for the Python community! 🙏

[alexanderankin]

Sounds good, I will revisit this issue when something breaks.

[amotl]

Hi. Thank you for this report. We found our CI breaking when updating to recent localstack/localstack:2026.3.

• CI: Validate LocalStack 2026.3 crate/cratedb-toolkit#726

[alexanderankin]

do previous images still work?

[amotl]

Yes, localstack/localstack:4.14 works well.

[alexanderankin]

I learned about this project today: https://github.com/hectorvent/floci

[amotl]

Nice. Thank you for sharing.

[vieiralucas]

@alexanderankin another option in a similar vein to floci: fakecloud. It's a Rust single binary that also runs on port 4566. The Docker image is at ghcr.io/faiscadev/fakecloud — no auth, no account.

If there's interest in having a fakecloud module alongside the LocalStack one, I'd be happy to contribute it.

Disclosure: I'm the author of fakecloud.

[alexanderankin]

currently i would not accept such a module until it gains significant traction as there is a maintenance burden involved. Right now what is in store for testcontainers-python is that we want to move a src based layout, then (and this will probably be breaking, so v5) i want to introduce a bunch of features from java and the "bloated enterprise java style" architecture choices from testcontainers-java (it works well and the python one leaves a lot to be desired). after this happens then I will be a lot more comfortable with my previous liberal policy of merging new modules. however, because of the tech debt currently being paid off (at a steep interest rate), i am basically in favor of same conservative new module policy of the official/more established testcontainers implementations. sorry. you are more than welcome to just publish your own to pypi, and then advertise it on the module registry - https://github.com/testcontainers/community-module-registry

[amotl]

Hi. David, you are doing an excellent job, thanks a stack for conceiving and maintaining testcontainers, we are looking forward to improvements of the Python stack. I think it will not hurt if Lucas will conceive a little testcontainers wrapper for fakecloud and publish it by other means, not contributing it to mainline just yet? Lucas: Good luck with fakecloud, thank you! 🍀

[amotl]

I learned about this project today.
Another option in a similar vein.

https://github.com/sivchari/kumo