Lambda

LocalEmu Lambda executes your function code in real Docker containers using the official AWS Lambda runtime images from public.ecr.aws/lambda. State persists across restarts when PERSISTENCE=1. Cold-start, container reuse, layers, versioning, aliases, VPC configuration, and event-source mappings all work end-to-end.

Coverage at the operation level: see the Lambda coverage matrix for which of the 85 Lambda operations are implemented.

Quick start

Create a function from a zip

$ cat > handler.py <<'EOF'
def lambda_handler(event, context):
    return {"statusCode": 200, "body": "hello from LocalEmu"}
EOF
$ zip handler.zip handler.py

$ awsemu lambda create-function \
    --function-name hello \
    --runtime python3.12 \
    --role arn:aws:iam::000000000000:role/lambda-role \
    --handler handler.lambda_handler \
    --zip-file fileb://handler.zip

FunctionArn: arn:aws:lambda:us-east-1:000000000000:function:hello
State: Active
Runtime: python3.12

No build step on LocalEmu's side. The zip is loaded into the runtime container at invocation time.

Invoke synchronously

$ awsemu lambda invoke \
    --function-name hello \
    --payload '{}' \
    /tmp/out.json

StatusCode: 200

$ cat /tmp/out.json
{"statusCode": 200, "body": "hello from LocalEmu"}

Invoke asynchronously

$ awsemu lambda invoke \
    --function-name hello \
    --invocation-type Event \
    --payload '{"k":"v"}' \
    /tmp/out.json

StatusCode: 202

Async invocations return 202 immediately, the queue dispatches to a container in the background, and retries follow AWS's exponential backoff (configurable, see LAMBDA_RETRY_BASE_DELAY_SECONDS).

Supported runtimes

Image format: public.ecr.aws/lambda/<family>:<version>. The runtime identifier you pass to --runtime maps to a tagged image in AWS's public ECR gallery. The image is pulled on first use and cached locally.

Container image functions (--package-type Image) bypass this mapping and run your image directly. Pull the runtime images ahead of time with LAMBDA_PREBUILD_IMAGES=1 if you want to avoid the first-invocation wait.

Executor architecture

LocalEmu ships one runtime executor: docker. Selected by LAMBDA_RUNTIME_EXECUTOR (default: docker). The executor spins up a container per cold start, keeps it warm between invocations, and tears it down after LAMBDA_KEEPALIVE_MS of idle time (default 10 minutes).

Container lifecycle:

• •
  Cold start: container does not exist, runtime image is pulled if missing, container is created, init runs.
• •
  Warm reuse: subsequent invocations within LAMBDA_KEEPALIVE_MS reuse the same container.
• •
  Idle teardown: container is stopped and removed after the keepalive window expires.
• •
  Concurrent invocations: a second container is spun up if all warm containers are busy, up to LAMBDA_LIMITS_CONCURRENT_EXECUTIONS.

Containers expose AWS_ENDPOINT_URL in the environment so boto3 inside your function reaches LocalEmu without any extra wiring. Unset this with LAMBDA_DISABLE_AWS_ENDPOINT_URL=1 if you need the function to use a different endpoint.

Limits and defaults

All limit env vars accept a raw byte count, so LAMBDA_LIMITS_CODE_SIZE_ZIPPED=104857600 raises the zipped-code limit to 100 MB.

Configuration

The full set of Lambda environment variables, grouped by purpose. Defaults are the values used when the variable is unset.

Executor and runtime images

Container and networking

Cold start and timing

Account-wide limits

Event source mapping

Retries, streams, and create timing

Debug and init binary

The init binary is the entrypoint LocalEmu injects into runtime containers (the same role AWS's aws-lambda-rie plays). These variables override its path, version, or runtime behaviour.

Features supported

Examples

Container-image function

$ awsemu ecr create-repository --repository-name my-fn
$ docker build -t my-fn .
$ docker tag my-fn 000000000000.dkr.ecr.us-east-1.localhost:4566/my-fn:latest
$ docker push 000000000000.dkr.ecr.us-east-1.localhost:4566/my-fn:latest

$ awsemu lambda create-function \
    --function-name my-fn \
    --package-type Image \
    --role arn:aws:iam::000000000000:role/lambda-role \
    --code ImageUri=000000000000.dkr.ecr.us-east-1.localhost:4566/my-fn:latest

PackageType: Image
State: Active

Publish a version, attach an alias

$ awsemu lambda publish-version --function-name hello
Version: 1

$ awsemu lambda create-alias \
    --function-name hello \
    --name prod \
    --function-version 1

AliasArn: arn:aws:lambda:us-east-1:000000000000:function:hello:prod

$ awsemu lambda invoke \
    --function-name hello:prod \
    --payload '{}' \
    /tmp/out.json
StatusCode: 200

Publish a layer, attach to the function

$ mkdir -p python && pip install requests -t python/
$ zip -r layer.zip python

$ awsemu lambda publish-layer-version \
    --layer-name shared-deps \
    --zip-file fileb://layer.zip \
    --compatible-runtimes python3.12 python3.11

LayerVersionArn: arn:aws:lambda:us-east-1:000000000000:layer:shared-deps:1

$ awsemu lambda update-function-configuration \
    --function-name hello \
    --layers arn:aws:lambda:us-east-1:000000000000:layer:shared-deps:1

SQS event source mapping

$ awsemu sqs create-queue --queue-name jobs
$ awsemu lambda create-event-source-mapping \
    --function-name hello \
    --event-source-arn arn:aws:sqs:us-east-1:000000000000:jobs \
    --batch-size 10

UUID: 8a7b6c5d-...
State: Enabled

$ awsemu sqs send-message \
    --queue-url http://sqs.us-east-1.localhost:4566/000000000000/jobs \
    --message-body '{"work":"item-1"}'

# Lambda is invoked asynchronously by the poller.
$ awsemu logs filter-log-events \
    --log-group-name /aws/lambda/hello \
    --query 'events[].message'

SQS, Kinesis, and DynamoDB Streams have dedicated pollers in services/lambda_/event_source_mapping/pollers/. Each runs in a background thread and respects the LAMBDA_EVENT_SOURCE_MAPPING_* backoff variables. Kafka (MSK and self-managed) accepts the same create-event-source-mapping call but dispatches via EventBridge Pipes under the hood.

Known limitations

Twenty of the 85 Lambda operations return NotImplementedException (501). Grouped by feature area:

• •
  Durable Executions (8 ops): GetDurableExecution, GetDurableExecutionHistory, GetDurableExecutionState, ListDurableExecutionsByFunction, SendDurableExecutionCallbackFailure, SendDurableExecutionCallbackHeartbeat, SendDurableExecutionCallbackSuccess, StopDurableExecution.
• •
  Capacity Providers (7 ops): CheckpointDurableExecution, CreateCapacityProvider, DeleteCapacityProvider, GetCapacityProvider, ListCapacityProviders, ListFunctionVersionsByCapacityProvider, UpdateCapacityProvider.
• •
  Scaling and runtime management config (4 ops): GetFunctionScalingConfig, PutFunctionScalingConfig, GetRuntimeManagementConfig, PutRuntimeManagementConfig.
• •
  Response streaming: InvokeWithResponseStream is not implemented.

Other behavioural caveats:

• •
  VPC config is stored on the function but security-group and subnet enforcement is not applied at the network layer. Functions can reach any host the LocalEmu process can reach.
• •
  EFS file system mounts are not supported. Use bind-mounted host directories via LAMBDA_DOCKER_FLAGS if you need shared file storage.
• •
  Cross-account layer fetching is not supported even when a role assumption would allow it on AWS.
• •
  Concurrent function-modification operations (publishing a version while updating configuration) have a known race condition. Serialise these calls in your tests.

The exact set of operations and their status is in the Lambda coverage matrix.