View a markdown version of this page

Building a runtime image from a Lambda base image - AWS Lambda

Building a runtime image from a Lambda base image

The fastest way to build a runtime image is to start from a Lambda base image. Each language base image already has the operating system, the language runtime, and the Lambda runtime interface client (RIC). You add your own components, such as an organization SDK, an extension, or a trusted certificate. Then you push the runtime image to Amazon Elastic Container Registry (Amazon ECR) and publish the image as a runtime version.

This topic shows how to build a runtime image from a Lambda base image. For the principles that apply to every runtime image, such as the file system layout and how Lambda starts the runtime, see Building runtime images.

About Lambda base images

Lambda publishes base images in the Amazon ECR Public Gallery. Each image URI has the format public.ecr.aws/lambda/runtime:version. The following table lists examples.

Examples of Lambda base images
Base image Contents
public.ecr.aws/lambda/python:3.14 Amazon Linux 2023, Python 3.14, and the Lambda RIC for Python
public.ecr.aws/lambda/nodejs:24 Amazon Linux 2023, Node.js 24, and the Lambda RIC for Node.js
public.ecr.aws/lambda/java:21 Amazon Linux 2023, Java 21, and the Lambda RIC for Java
public.ecr.aws/lambda/dotnet:8 Amazon Linux 2023, .NET 8, and the Lambda RIC for .NET
public.ecr.aws/lambda/ruby:3.4 Amazon Linux 2023, Ruby 3.4, and the Lambda RIC for Ruby
public.ecr.aws/lambda/provided:al2023 Amazon Linux 2023 only, with no language runtime or RIC

Each language base image has the same components as the Lambda-managed runtime for that language. For the full list of base images, see Using an AWS base image for Lambda. The OS-only base image (provided:al2023) contains Amazon Linux 2023 but no language runtime. You can use the OS-only base image as a starting point to add your own language runtime. For more information about the OS-only base image, see Choosing a base image.

Lambda base images have the following configuration:

  • ENTRYPOINT is ["/lambda-entrypoint.sh"].

  • CMD isn't set.

  • WORKDIR is /var/task.

Keep the base image's ENTRYPOINT unless you have a specific reason to change the ENTRYPOINT. Don't set a CMD, and don't put a function handler in the runtime image. Lambda passes the handler from the function configuration to /lambda-entrypoint.sh. For more information, see How Lambda base images start the runtime.

How Lambda base images start the runtime

Every runtime image must follow the startup contract that How Lambda starts your runtime describes. Lambda base images implement the startup contract for you.

Lambda base images set ENTRYPOINT to /lambda-entrypoint.sh and don't set a CMD. The working directory in Lambda base images is /var/task. A Lambda base image starts the runtime in the following order:

  1. Lambda runs /lambda-entrypoint.sh with the handler as the only argument. The script exits with an error if the script receives a different number of arguments.

  2. The script sets the _HANDLER environment variable to the handler, and then runs /var/runtime/bootstrap.

  3. The bootstrap starts the language runtime, which runs the Lambda RIC.

  4. The RIC reads _HANDLER to find the function code and the handler function.

For example, a Python function might have the handler lambda_function.lambda_handler. Lambda runs a command similar to the following:

/lambda-entrypoint.sh lambda_function.lambda_handler

The script sets _HANDLER to lambda_function.lambda_handler, and then starts /var/runtime/bootstrap. During initialization, the RIC loads the lambda_function module, which is the file lambda_function.py in /var/task. For each invocation, the RIC calls the lambda_handler function. For more information about the Python handler format, see Define Lambda Event Function handler in Python.

When you run the image outside Lambda, for example on your local machine, the AWS_LAMBDA_RUNTIME_API environment variable isn't set. In this case, /lambda-entrypoint.sh runs /var/runtime/bootstrap under the runtime interface emulator (RIE), /usr/local/bin/aws-lambda-rie. You can use the RIE to test your runtime image locally.

Because Lambda base images don't set a CMD, a runtime image that you build on a Lambda base image doesn't inherit a handler.

If you replace the ENTRYPOINT in a runtime image that you build on a Lambda base image, /lambda-entrypoint.sh no longer runs. In this case, Lambda doesn't set the _HANDLER environment variable. Your program must read the handler from the arguments that Lambda passes, or set _HANDLER itself.

Adding your components

Add your components on top of the base image in your Dockerfile. Every function that uses the runtime gets these components. The following table shows where to put each kind of component.

Where to put components in a runtime image
Component Location
Python libraries Install with pip install, without the --target option. In Python 3.11 and later base images, pip installs packages in /var/lang/lib/python3.x/site-packages, with the runtime-included libraries. pip then reports any conflicts with the runtime-included libraries when you build the image. For more information, see Dependency search path in the base images.
Node.js libraries Put libraries in /var/runtime/node_modules. In Lambda base images, /var/runtime/node_modules is on the NODE_PATH search path. The Lambda base image build of Node.js searches NODE_PATH for both CommonJS modules and ES modules (ESM). Standard Node.js searches NODE_PATH for CommonJS modules only. For more information, see Dependency search path and runtime-included libraries.
Libraries for other languages Put libraries in /var/runtime, and make sure that the language runtime's search path includes the library location. For more information, see Adding code libraries and extensions.
Extensions Copy extension executables to /var/runtime-opt/extensions. Lambda starts each file in the directory, so put only extension executables in the directory. For more information, see Adding code libraries and extensions.
Certificates Add certificates to the operating system trust store. On Amazon Linux 2023, copy the certificate to /etc/pki/ca-trust/source/anchors, and then run update-ca-trust.
Configuration files Put configuration files in any directory except /opt, /var/task, and /tmp. For example, use /etc or /var/runtime.

Function code can override the libraries in your runtime. The language runtime searches /var/task first, so a library in the function's .zip file archive has precedence over the same library in the runtime image. Function layers can also add or override libraries and extensions.

Some libraries don't use the operating system trust store. For example, the Python requests library uses the certificates from the certifi package by default, and Node.js uses a certificate store that's built into Node.js. Check how each library in your runtime finds certificates.

When you add components, follow these rules:

  • Don't put anything in /opt, /var/task, or /tmp. Lambda uses these directories for layers, function code, and temporary storage. For more information, see File system layout.

  • Use absolute paths in COPY and RUN instructions. The base image sets WORKDIR to /var/task, so a relative path puts files in /var/task.

  • Don't replace the base image's language runtime, RIC, or /var/runtime/bootstrap. To change these components, build from scratch instead. For more information, see Building runtime images from scratch.

  • Don't put secrets in the runtime image. Function code can read everything in the runtime image. For more information, see What goes into a runtime image.

Choosing architectures

Lambda base images are available for both the x86_64 and arm64 architectures. To choose an architecture, use the --platform option when you build the image:

  • --platform linux/amd64 builds an x86_64 runtime image.

  • --platform linux/arm64 builds an arm64 runtime image.

  • --platform linux/amd64,linux/arm64 with docker buildx builds a multi-architecture runtime image that supports both architectures.

If you add binary files, such as a native extension, add the correct binary file for each architecture. For more information, see Architectures.

Declaring capabilities

A runtime image that you build from a Lambda base image declares capabilities in the same way as any other runtime image. For example, to let functions on Lambda Managed Instances use your runtime, add the Lambda Managed Instances label to the image. For more information, see Lambda Managed Instances. Lambda base images set the integration model and Lambda Managed Instances labels, which your image inherits. You can override a label with your own LABEL instruction.

Keeping your runtime patched

Lambda regularly updates the base images with security patches. However, Lambda doesn't update your runtime image or your runtime versions. To pick up the patches, rebuild your runtime image from the updated base image. Then publish the new runtime image as a new runtime version, and update your runtime aliases. You must also patch the components that you add. For more information, see Deploying runtime updates.

The FROM instruction can refer to the base image in three ways. You can use a mutable tag, a version-specific tag, or a digest. The following table compares the three options.

Ways to refer to a base image in the FROM instruction
Option Example Trade-offs
Mutable tag FROM public.ecr.aws/lambda/python:3.14 Lambda moves the tag to each new patched base image. Every rebuild picks up the latest patches automatically. Builds aren't reproducible, because two builds of the same Dockerfile can produce different runtime images.
Version-specific tag (immutable) FROM public.ecr.aws/lambda/python:3.14.2026.02.23.16 Lambda publishes a version-specific tag for each base image release. The tag doesn't change, so builds are reproducible. The tag is also easier to read than a digest. To pick up patches, update the tag to a newer release.
Digest FROM public.ecr.aws/lambda/python@sha256:digest A digest never changes, so builds are reproducible. A digest is harder to read than a tag. To pick up patches, update the digest.

Version-specific tags have the format tag.YYYY.MM.DD.HH, with an optional -x86_64 or -arm64 suffix. For example, public.ecr.aws/lambda/python:3.14.2026.11.13.18. To find the tags for a base image, see the Image tags tab for the image in the Amazon ECR Public Gallery. For example, see the Python base image.

If you use a version-specific tag or a digest, automate the updates. For example, a scheduled job or a dependency update tool can check for a new base image release. The job or tool can then open a change request to update the tag or digest in your Dockerfile.

We recommend that you rebuild and publish your runtime in an automated pipeline. A pipeline makes regular patching practical, and the pipeline tests every update in the same way. For more information, see Building a runtime update pipeline.

Lambda stops updating a base image when Lambda deprecates the matching runtime, so the base image no longer gets security patches. You have the following options:

  • Align your deprecation lifecycle with the base image that you build on. Set the deprecation date of your runtime, or of your alias, to the deprecation date of the matching Lambda runtime.

  • Move your runtime to a base image for a supported Lambda runtime before the deprecation date.

  • Take over patching the base image yourself.

For more information about the Lambda deprecation policy, see Runtime deprecation.

Example Dockerfiles

The following examples show Dockerfiles for runtime images that start from a Lambda base image.

Python 3.14 with an organization SDK and a certificate

The following Dockerfile starts from the Python 3.14 base image. The Dockerfile installs an organization SDK from a wheel file, and adds a private certificate authority (CA) certificate to the trust store. The --mount option makes the wheel file available during the build without copying the wheel file into the runtime image.

FROM public.ecr.aws/lambda/python:3.14 # Install the organization SDK into the runtime's site-packages directory. RUN --mount=type=bind,source=wheels,target=/wheels \ pip install --no-cache-dir /wheels/my_org_sdk-2.4.0-py3-none-any.whl # Add the organization's private CA certificate to the trust store. COPY certs/my-org-root-ca.pem /etc/pki/ca-trust/source/anchors/my-org-root-ca.pem RUN update-ca-trust # Don't set CMD. Lambda passes the handler from the function configuration.

The example expects the following files in the build context:

  • wheels/my_org_sdk-2.4.0-py3-none-any.whl – The organization SDK

  • certs/my-org-root-ca.pem – The CA certificate in PEM format

The --mount option requires BuildKit, which is the default builder in current versions of Docker.

Node.js 24 with an extension

The following Dockerfile starts from the Node.js 24 base image and adds a runtime-level extension. The Dockerfile uses the TARGETARCH build argument to copy the extension binary file for each architecture. With this approach, you can build a multi-architecture runtime image from one Dockerfile.

FROM public.ecr.aws/lambda/nodejs:24 # Docker sets TARGETARCH to amd64 or arm64 for each platform in the build. ARG TARGETARCH # Add the telemetry extension as a runtime-level extension. COPY extensions/${TARGETARCH}/my-telemetry-extension /var/runtime-opt/extensions/my-telemetry-extension RUN chmod 755 /var/runtime-opt/extensions/my-telemetry-extension # Don't set CMD. Lambda passes the handler from the function configuration.

The example expects the extension binary files in extensions/amd64/my-telemetry-extension and extensions/arm64/my-telemetry-extension. The extension must register with the Lambda Extensions API. For more information, see Using the Lambda Extensions API to create extensions.

Build and push a runtime image

Build the runtime image with Docker, and push the runtime image to Amazon ECR. Then create a runtime version from the runtime image. You build runtime images with Docker tools, so the Lambda console has no steps for this task.

Before you start, make sure that you have the following:

The examples use account 123456789012, the us-east-1 Region, and an Amazon ECR repository and runtime named companypython. Each build gets a unique, date-based tag, such as 2026-10-08.1.

To build and push a runtime image (AWS CLI)
  1. To authenticate Docker to your Amazon ECR registry, run the following command:

    aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin 123456789012.dkr.ecr.us-east-1.amazonaws.com
  2. In the directory that contains your Dockerfile, run the docker buildx build command. The --push option pushes the runtime image to Amazon ECR after the build.

    To build a single-architecture runtime image, specify one platform:

    docker buildx build \ --platform linux/arm64 \ --tag 123456789012.dkr.ecr.us-east-1.amazonaws.com/companypython:2026-10-08.1 \ --push .

    To build a multi-architecture runtime image, specify both platforms:

    docker buildx build \ --platform linux/amd64,linux/arm64 \ --tag 123456789012.dkr.ecr.us-east-1.amazonaws.com/companypython:2026-10-08.1 \ --push .
  3. To confirm that Amazon ECR has the runtime image, run the describe-images command:

    aws ecr describe-images \ --repository-name companypython \ --image-ids imageTag=2026-10-08.1 \ --region us-east-1

    The output shows the image digest, tags, and push time.

Your runtime image is now ready. Next, create a runtime version from the runtime image. Then roll the new runtime version out to your functions. For more information, see Deploying runtime updates.

(Optional) Test your runtime image locally

Lambda base images include the runtime interface emulator (RIE). When you run the runtime image outside Lambda, /lambda-entrypoint.sh starts the runtime under the RIE. You can use the RIE to invoke a sample function with your runtime image before you publish a runtime version. For more information, see How Lambda base images start the runtime.

To test a runtime image locally
  1. In an empty directory, create a file named lambda_function.py with sample function code. The following example imports the organization SDK from the Python example Dockerfile:

    import my_org_sdk def lambda_handler(event, context): return {"sdkVersion": my_org_sdk.__version__}
  2. From the same directory, run the following command. The command mounts the directory as read-only /var/task, and passes the handler as the command argument.

    docker run --rm --platform linux/arm64 -p 9000:8080 \ -v "$PWD":/var/task:ro \ 123456789012.dkr.ecr.us-east-1.amazonaws.com/companypython:2026-10-08.1 \ lambda_function.lambda_handler

    The --platform value must match an architecture in the runtime image. To run an image for a different architecture than your computer, Docker must support emulation.

  3. From a new terminal window, invoke the function with curl:

    curl "http://localhost:9000/2015-03-31/functions/function/invocations" -d '{}'

    You should see output similar to the following:

    {"sdkVersion": "2.4.0"}
  4. To stop the container, press Ctrl+C in the terminal window where the container runs.

The RIE starts extensions only from /opt/extensions. To test a runtime-level extension locally, also copy it to /opt/extensions in a test image.

Next steps

After you push your runtime image, continue with the following topics: