LocalStack v2.0 offers a completely rewritten implementation of our local Lambda service with improved performance, feature coverage, AWS parity, and many more improvements. This new lambda provider
v2 (formerly known as
asf) supports 95% of all Lambda API operations and behaves like in AWS. Our documentation describes migrating to Lambda v2 in detail.
- Feature coverage: LocalStack supports 95% of all Lambda API operations.
- AWS Parity: The local Lambda API behaves like in AWS with 90% parity test coverage.
- Official AWS images: Lambda functions use the official Docker base images pulled from
- Lambda runtimes: All supported managed runtimes from AWS are available and tested in LocalStack. The new provider added
- ARM support: Run arm64 and x86_64 Lambda functions on hosts with multi-architecture support.
- Extensions API: Use third-party extensions to customize the Lambda execution environment. This deep integration enables monitoring, observability, or advanced developer tooling.
- Lambda concurrency: Prevent cold-starts with provisioned concurrency and limit the number of concurrent function instances with reserved concurrency.
- Performance: 10ms warm-start and 600ms cold-start for an Echo Python Lambda
- Hot reloading: Continuously apply code changes to Lambda functions and layers (Pro) for all managed runtimes.
- Persistence and Cloud Pods: Save your Lambda state across restarts and share a snapshot of your Lambda infrastructure.
- Permissions: CRUD operations for resource-based policies are now fully supported and thoroughly tested (e.g., AddPermission).
- API-level validations: Stricter input validation detects syntax errors early and raises the same exceptions as in AWS. For example,
r1is an invalid execution role because it does not match ARN format
- Function state lifecycle: Creating and updating lambda functions happens asynchronously following the Lambda state lifecycle. Functions are always created in the
Pendingstate and move to
Activeonce ready to accept invocations.
- Runtime parity: Compared to AWS, Lambda functions run as the same user with (almost) the same environment variables and mostly the same quota (some ulimits are intentionally opt-in).
- Function versions and aliases: Improved support and thorough test coverage.
- Layer CRUD Open-Source: Basic CRUD operations are available in LocalStack Community but using any layers at runtime requires a Pro subscription.
- Shared Lambda layers (Pro): Fetching shared lambda layers hosted on AWS is faster and supports ARM layers. Get inspired by awesome-layers.
- Asynchronous event handling: Handle asynchronous events with retries and exceptions.
- Lambda function URLs: Improved handling and better test coverage.
- Invocation response: Improved capturing and rendering of invocation results (e.g., Payload, LogResult, FunctionError) when invoking functions.
- Function timeouts: Reliably enforced like in AWS.
- X-Ray (Pro): Integrated the official AWS X-Ray daemon for collecting distributed traces from instrumented handlers.
This section describes the behavioral changes related to the Lambda API, Docker Execution Environment, Configuration, and Hot Reloading.
Improved parity compared to AWS: Lambda API methods in LocalStack behave like in AWS. This was not always the case in the old provider without systematic testing. If you discover a difference between LocalStack and AWS in the new provider, please report a bug on GitHub.
Stricter input validation: Expect more exceptions in the new provider due to invalid input. For example, the old provider accepted arbitrary strings such as
r1 as a lambda role when creating a function. The new provider validates the role ARN in the format
arn:aws:iam::000000000000:role/lambda-role using an appropriate regex but currently does not check whether it exists.
Asynchronous function creation: Creating and updating lambda functions now happens asynchronously following the AWS Lambda state model. The old provider created functions synchronously by blocking until the function state was active. In the new provider, functions are always created in the
Pending state and move to
Active once they are ready to accept invocations. Migration instructions are provided in the troubleshooting example Function in Pending state.
Docker socket mounting required: Mounting the Docker socket into the LocalStack container is now required to run lambda functions. Please add the Docker volume mount
"/var/run/docker.sock:/var/run/docker.sock" to your LocalStack startup as exemplified in our official docker-compose.yml. If mounting the Docker socket is impossible and no external
DOCKER_HOST is available, self-managed worker containers will be available (coming soon).
Local executor mode is discontinued: The Lambda Executor Modes such as
LAMBDA_EXECUTOR=local are discontinued in the new provider. In the old provider, lambda functions were executed within the LocalStack container in the local executor mode. It was primarily used as a fallback if the Docker socket was unavailable in the LocalStack container. Hence, many users unintentionally used the local executor mode despite configuring
LAMBDA_EXECUTOR=docker. The new provider requires no such configuration and now behaves similarly to the old
No container restart after each invocation: Lambda containers are reused between invocations. Therefore, filesystem changes (for example, in
/tmp) persist between subsequent invocations if dispatched to the same container. It is called a “warm start” (see Operating Lambda). If you want to force “cold starts”, you could set
LAMBDA_KEEPALIVE_MS to 0 milliseconds.
Official AWS-provided Lambda images: The new provider uses the official AWS base images for Lambda pulled from
public.ecr.aws/lambda/ instead of
lambci images. Hence, Lambda functions’ filesystem now matches the AWS Lambda production environment.
ARM64 lambda functions: Lambda now supports ARM containers for compatible runtimes based on Amazon Linux 2. ARM-compatible hosts can create functions with the
More details are provided under ARM64 support.
Transparent endpoint injection in LocalStack Pro: Lambda functions resolve AWS domains such as
s3.amazonaws.com to the LocalStack container. This domain resolution is now completely DNS-based and can be disabled by setting
DNS_ADDRESS=0. For more details, please refer to Transparent Endpoint Injection. The old provider provided patched AWS SDKs to redirect AWS API transparently calls to LocalStack.
The following configuration options from the old provider are discontinued in the new provider:
LAMBDA_EXECUTORand, in particular,
LAMBDA_EXECUTOR=localshould be removed (see “Local executor mode is discontinued” above).
LAMBDA_STAY_OPEN_MODEis now the default behavior and can be removed. Instead,
LAMBDA_KEEPALIVE_MScan be used to configure how long containers should be kept running in-between invocations.
LAMBDA_REMOTE_DOCKERis not used anymore because the new provider always copies zip files and automatically configures hot reloading.
LAMBDA_CODE_EXTRACT_TIMEis no longer used because function creation now happens asynchronously.
LAMBDA_CONTAINER_REGISTRYis not used anymore. Use the more flexible
LAMBDA_RUNTIME_IMAGE_MAPPINGto customize individual runtimes.
LAMBDA_FALLBACK_URLis not supported anymore.
LAMBDA_FORWARD_URLis not supported anymore.
LAMBDA_JAVA_OPTSis currently not directly supported anymore. It is configurable via a custom wrapper script.
HOSTNAME_FROM_LAMBDAis not supported anymore.
LAMBDA_XRAY_INITis no longer needed because the X-Ray daemon is always initialized.
SYNCHRONOUS_SNS_EVENTSare not supported anymore.
The new provider still supports the following configuration options:
BUCKET_MARKER_LOCALhas a new default value,
hot-reload(new), because the former default
__local__(old) is an invalid bucket name.
LAMBDA_DOCKER_DNSis supported in LocalStack >2.1 (
Hot Reloading (formerly known as hot swapping) continuously applies code changes to Lambda functions without manual redeployment.
Default S3 bucket name changed: The default magic S3 bucket name changed from
hot-reload. Please change your deployment configuration accordingly, or use the
BUCKET_MARKER_LOCAL configuration to customize the value.
Delay in code change detection: It can take up to 700ms to detect code changes.
In the meantime, invocations still execute the former code. Hot reloading triggers after 500ms without changes can take up to 200ms until the change is notified. In the old provider, changes were reflected instantly using code mounting but container restarting added extra delay.
Runtime restart after each code change: The runtime inside the container is restarted after every code change. During the runtime restart, the handler function re-executes any initialization code outside your handler function. The container itself is not restarted. Therefore, filesystem changes persist between code changes for invocations dispatched to the same container.
File sharing permissions with Docker Desktop on macOS: If using Docker Desktop on macOS, you might need to allow file sharing for your target folders. MacOS may prompt you to grant Docker access to your target folders.
Startup configuration automated: Hot reloading now works without additional LocalStack startup configuration. In the old provider, starting LocalStack with
LAMBDA_REMOTE_DOCKER=0 was required. This configuration is not used anymore because the new provider always copies zip files and automatically configures hot reloading.
How can I use the new Lambda provider?
Update to LocalStack ≥2.0 and the new Lambda provider is active by default.
What do I need to do to use the new Lambda provider?
Please check out our guide about migrating to Lambda v2. Most likely,
- Add the Docker volume mount
- Before invoking a function, wait until the function becomes Active using a waiter.
- If using hot reloading, change the magic S3 bucket name from
How can I fix errors related to Docker not available?
How can I fix the ResourceConflictException when trying to invoke a function?
Wait until the function transitions from the state Pending to Active using a waiter, for example,
awslocal lambda wait function-active-v2 --function-name my-function
Check out our troubleshooting guide.
How can I use the old Lambda provider (deprecated)?
The old lambda provider is temporarily available in LocalStack v2 using
PROVIDER_OVERRIDE_LAMBDA=legacybut we highly recommend migrating to the new lambda provider. Please let us know on GitHub or LocalStack Pro Support if you experience any issues.