Building runtime images from scratch
To build a runtime image from scratch, you start from a base image that has no language runtime. Then you add a language runtime, one of the open-source Lambda runtime interface clients (RICs), and a bootstrap that starts the runtime. You push the runtime image to Amazon Elastic Container Registry (Amazon ECR), and then publish the runtime image as a runtime version.
Build a runtime image from scratch in the following cases:
-
You need a language version or distribution that no Lambda base image offers. For example, you might need a different minor version, or a build with different compile options.
-
You need an operating system (OS) other than Amazon Linux 2023.
-
You need strict control over every component in the runtime image, for example to meet security or compliance rules.
When you build from scratch, you own more of the runtime image than when you start from a Lambda base image. You choose, install, and patch the language runtime and the RIC. If you use your own base image, you also own and patch the OS libraries. If you only need to add libraries, extensions, or certificates to a language that Lambda supports, start from a Lambda base image instead. For more information, see Building a runtime image from a Lambda base image.
To support a language that has no Lambda RIC, you write your own RIC. For more information, see Supporting a new programming language for AWS Lambda Event Functions.
This topic covers the implementation steps. For the principles that apply to every runtime image, such as the file system layout and image best practices, see Building runtime images.
If you already build container image functions, the Dockerfile for a runtime image looks familiar. However, a runtime image doesn't contain function code or a CMD. Functions that use your runtime are .zip file archive functions. For more information about container image functions, see Create a Lambda Event Function using a container image.
Choosing a base image
A runtime image that you build from scratch starts from one of the following kinds of base image:
-
A Lambda OS-only base image – The OS-only base image
, public.ecr.aws/lambda/provided:al2023, has no language runtime or RIC. The OS-only base image contains the following:-
Amazon Linux 2023
-
/lambda-entrypoint.sh, which is the image'sENTRYPOINT -
The runtime interface emulator (RIE), for local testing
-
The environment variables that Lambda runtimes need
-
/var/taskas the working directory
Lambda patches the OS in the OS-only base image. To get the OS patches, rebuild your runtime image. For more information, see OS-only runtimes.
-
-
Your own base image – A base image of your choice, such as an image with a different Linux distribution. You provide every component, including the startup files and environment variables that the OS-only base image provides. You also patch every component. For the environment variables to set, and the variables that Lambda sets for you, see Setting environment variables in the runtime image.
We recommend that you start from the Lambda OS-only base image. The OS-only base image already works with the way that Lambda starts the runtime, and Lambda keeps the OS patched.
The runtime startup contract
A runtime image that you build from scratch must start the runtime in the way that Lambda expects. When Lambda sets up an execution environment for a function, Lambda runs the executable that the image's ENTRYPOINT specifies. Lambda passes the function's handler to the executable as the last argument. The handler is the Handler property in the function configuration. If the ENTRYPOINT includes its own arguments, Lambda appends the handler after them. For example, with ENTRYPOINT ["/var/runtime/bootstrap", "--flag"], the bootstrap receives --flag and then the handler.
If the image doesn't set an ENTRYPOINT, Lambda runs /var/runtime/bootstrap with the handler as the argument. If the image sets no ENTRYPOINT and includes no /var/runtime/bootstrap, invocations fail with the error type Runtime.InvalidEntrypoint. Lambda doesn't use the image's CMD, so don't put the handler in ENTRYPOINT or CMD. Lambda places the function code in /var/task. For a summary that applies to every runtime image, see How Lambda starts your runtime.
Lambda doesn't set the _HANDLER environment variable for a runtime that you build from scratch. Your runtime must read the handler from the arguments, or set _HANDLER itself. The Lambda base images set _HANDLER for you because the /lambda-entrypoint.sh script copies the handler into the variable.
Your runtime is responsible for the following tasks:
-
During initialization, use the handler to find and load the function code from
/var/task. -
For each invocation, call the handler.
-
Use the Lambda runtime API to get events and to send responses and errors. For more information, see Using the Lambda runtime API.
When you use a Lambda RIC, the RIC does these tasks for you. Your runtime defines the handler format. The handler format typically follows the conventions of the runtime's programming language. For compiled languages, the executable that ENTRYPOINT specifies can contain the RIC itself.
Choosing an entrypoint
You can start your runtime in one of the following ways:
-
Reuse
/lambda-entrypoint.sh– If you start from the OS-only base image, keep the inheritedENTRYPOINT. The/lambda-entrypoint.shscript sets the_HANDLERenvironment variable to the handler, and then runs/var/runtime/bootstrap. You provide the bootstrap. Outside Lambda, the script runs the bootstrap under the RIE, so you can test the runtime image locally. For more information, see How Lambda base images start the runtime. -
Write your own entrypoint – Set
ENTRYPOINTto your own executable. The executable receives the handler as the last argument. If neither your base image nor your Dockerfile sets anENTRYPOINT, Lambda runs/var/runtime/bootstrap. To test locally, run your entrypoint under the RIE. For more information, see (Optional) Test your runtime image locally.
We recommend that you reuse /lambda-entrypoint.sh when you start from the OS-only base image.
Use the exec form of ENTRYPOINT, which is a JSON array, so that Lambda can pass the handler to your runtime. With the shell form, Docker stores the entrypoint as /bin/sh -c, and your runtime never receives the handler. The following example shows both forms:
# Correct: exec form. Lambda passes the handler to the entrypoint. ENTRYPOINT ["/var/runtime/bootstrap"] # Wrong: shell form. The runtime never receives the handler. # ENTRYPOINT /var/runtime/bootstrap
Writing the bootstrap
The bootstrap starts the language runtime, and the language runtime runs the RIC. The bootstrap passes the handler to the RIC. A bootstrap is typically a short shell script. When you write the bootstrap, follow these guidelines:
-
Make the bootstrap executable, for example with chmod 755.
-
Set the language search paths before the bootstrap starts the language runtime. For more information, see Adding a language runtime.
-
Start the language runtime with exec. The language runtime process then replaces the shell process.
-
Optionally, support wrapper scripts. If the function sets the
AWS_LAMBDA_EXEC_WRAPPERenvironment variable, run the wrapper script, passing the language runtime command and its arguments. For more information, see Wrapper scripts.
For an example bootstrap, see Example: Python runtime from the OS-only base image.
Adding a language runtime
Add the interpreter or virtual machine for your language to the runtime image. Consider the following when you add a language runtime:
-
Where to install the language runtime – Lambda base images install the language runtime in
/var/lang. The defaultPATHandLD_LIBRARY_PATHvalues include/var/lang/binand/var/lang/lib. If you install the language runtime from the OS package manager, the package manager chooses the location, such as/usr/bin. Don't install the language runtime in/opt,/var/task, or/tmp. For more information, see File system layout. -
Which version to install – Choose a version that gets security updates for as long as you plan to support the runtime. The end of support for the language version can determine when you deprecate the runtime. For more information, see Runtime lifecycle.
-
Language search paths – Configure the language runtime to find function code in
/var/task, libraries from layers in/opt, and your libraries in/var/runtime. For example, setPYTHONPATHfor Python orNODE_PATHfor Node.js. Set the search paths in the bootstrap or with the DockerfileENVinstruction.
To match the behavior of Lambda-managed runtimes, use the same search path order. For example, see Dependency search path and runtime-included libraries and Dependency search path and runtime-included libraries.
Lambda base images search function code (/var/task) first, then layer paths, and then the runtime's own libraries. For Python, the layer paths are /opt/python/lib/python and X.Y/site-packages/opt/python. For Node.js, they're /opt/nodejs/node and NN/node_modules/opt/nodejs/node_modules.
Adding a Lambda runtime interface client
The RIC loads the function handler, gets events from Lambda, and sends back responses. Lambda publishes RICs for several languages as open source. For the list of RICs, their packages, and their source code repositories, see Open-source repositories.
Install the RIC in /var/runtime, or in another location that the language search path includes. Keep the RIC up to date. New RIC releases can include fixes and support for new Lambda features.
In your bootstrap, pass the handler to the RIC. With /lambda-entrypoint.sh, the handler is in the _HANDLER environment variable. If you write your own entrypoint, read the handler from the arguments that Lambda passes. For the handler format for each language, see Programming languages.
Setting environment variables in the runtime image
Your runtime, function code, and layers need environment variables, such as PATH and LAMBDA_TASK_ROOT, to work as expected. Some variables come from the runtime image, and Lambda sets others when it starts the runtime. You set environment variables in the runtime image with the Dockerfile ENV instruction. Your runtime and the function code can read these variables at run time.
If you build from a Lambda base image, including the OS-only base image, the runtime image inherits the environment variables in the following table. You don't need to set them.
If you use your own base image, set the following environment variables:
-
PATH– Include the directories for your language runtime and tools. Your runtime uses thePATHvalue from the image. -
Language-specific variables – Set any variables that your language runtime needs, such as
PYTHONPATHfor Python orNODE_PATHfor Node.js. Set them in your bootstrap or withENV. Lambda base images set language-specific search paths in the bootstrap, not withENV. For more information, see Adding a language runtime.
When Lambda starts the runtime, it always sets LAMBDA_TASK_ROOT and LAMBDA_RUNTIME_DIR. It sets LANG, TZ, and LD_LIBRARY_PATH only if the image doesn't set them. For example, if the image doesn't set TZ, Lambda sets it to :UTC. You don't need to set these variables in the image. The RIE doesn't set these variables. To test the runtime image locally, pass them when you run the container. For more information, see (Optional) Test your runtime image locally.
Lambda doesn't set _HANDLER for a runtime that you build from scratch. Unless your entrypoint sets _HANDLER, your bootstrap must read the handler from its arguments. For more information, see The runtime startup contract.
The following table lists the environment variables that Lambda base images set. For LAMBDA_TASK_ROOT and LAMBDA_RUNTIME_DIR, the table also shows the values that Lambda uses when it starts the runtime.
| Variable | Purpose | Value in Lambda base images |
|---|---|---|
LANG |
Sets the locale, including the default character encoding. | en_US.UTF-8 |
TZ |
Sets the time zone from the system time zone file, /etc/localtime. |
:/etc/localtime (UTC) |
PATH |
Lists the directories to search for executables. The list includes the language runtime (/var/lang/bin) and executables from layers (/opt/bin). |
/var/lang/bin:/usr/local/bin:/usr/bin/:/bin:/opt/bin |
LD_LIBRARY_PATH |
Lists the directories that the dynamic linker searches for shared libraries (.so files) before the system defaults. The list includes libraries for the language runtime (/var/lang/lib) and for the runtime (/var/runtime). The list also includes native libraries in the function code (/var/task/lib) and in layers (/opt/lib). |
/var/lang/lib:/lib64:/usr/lib64:/var/runtime:/var/runtime/lib:/var/task:/var/task/lib:/opt/lib |
LAMBDA_TASK_ROOT |
Sets the path to the function code. Lambda runtimes use the value to find and load the function code. For example, the Python runtime adds the value to the module search path. | /var/task |
LAMBDA_RUNTIME_DIR |
Sets the path to the runtime files. | /var/runtime |
Lambda also sets reserved environment variables at run time, such as AWS_REGION, AWS_LAMBDA_FUNCTION_NAME, and AWS_LAMBDA_RUNTIME_API. Don't set reserved environment variables in the runtime image. For a list of reserved environment variables, see Defined runtime environment variables.
Your runtime can also read the environment variables in the function configuration. For more information, see Working with Lambda environment variables.
Function environment variables override variables with the same name in the runtime image.
Don't put secrets in environment variables in the runtime image. Function code can read every environment variable that the image sets. For more information, see What goes into a runtime image.
Declaring capabilities
A runtime image that you build from scratch 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. Your runtime must also handle multiple invocations at the same time in one execution environment. For more information, see Lambda Managed Instances.
Example: Python runtime from the OS-only base image
The following example builds a Python runtime image from the OS-only base image. The Dockerfile installs Python 3.14, the latest Python version in the Amazon Linux 2023 package repositories. Then the Dockerfile installs the Python RIC in /var/runtime, and adds a bootstrap. For the Python RIC package, see Open-source repositories. The runtime image keeps the inherited ENTRYPOINT, /lambda-entrypoint.sh.
The example expects the following files in the build context:
-
Dockerfile– The instructions to build the runtime image -
bootstrap– The script that starts the Python RIC
The following example shows the Dockerfile:
FROM public.ecr.aws/lambda/provided:al2023 # Install the Python interpreter and pip from the Amazon Linux 2023 repositories. RUN dnf install -y python3.14 python3.14-pip && dnf clean all # Install the Lambda runtime interface client for Python in /var/runtime. RUN python3.14 -m pip install --no-cache-dir --target /var/runtime awslambdaric # Add the bootstrap. /lambda-entrypoint.sh runs /var/runtime/bootstrap. COPY bootstrap /var/runtime/bootstrap RUN chmod 755 /var/runtime/bootstrap # Keep the inherited ENTRYPOINT. Don't set CMD. # Lambda passes the handler from the function configuration.
The following example shows the bootstrap script. /lambda-entrypoint.sh sets _HANDLER before the script runs. The script sets the Python search path, and then starts the Python RIC with the handler. If the function sets AWS_LAMBDA_EXEC_WRAPPER, the script runs the Python RIC through the wrapper script.
#!/bin/sh # Function code first, then layers, then the runtime's own libraries. export PYTHONPATH="/var/task:/opt/python/lib/python3.14/site-packages:/opt/python:/var/runtime" if [ -n "$AWS_LAMBDA_EXEC_WRAPPER" ]; then exec "$AWS_LAMBDA_EXEC_WRAPPER" /usr/bin/python3.14 -m awslambdaric "$_HANDLER" fi exec /usr/bin/python3.14 -m awslambdaric "$_HANDLER"
Save the bootstrap file with Unix line endings (LF). A script with Windows line endings (CRLF) fails to run.
Functions that use this runtime set the handler in the Python format, for example lambda_function.lambda_handler. For more information, see Define Lambda Event Function handler in Python.
Build and push the runtime image
You build and push a runtime image from scratch in the same way as a runtime image from a Lambda base image. For the procedure, see Build and push a runtime image. Use your own Amazon ECR repository name and image tag in the commands.
If you build a multi-architecture runtime image, make sure that every component works on both architectures. Most OS packages and RIC packages are available for both architectures. Any binary file that you copy into the image must match each architecture. For more information, see Architectures.
After you push the runtime image, 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
The OS-only base image includes the runtime interface emulator/lambda-entrypoint.sh as the ENTRYPOINT, the script starts the runtime under the RIE when you run the runtime image outside Lambda.
To test a runtime image from the OS-only base image locally
-
In an empty directory, create a file named
lambda_function.pywith sample function code. The following example returns the Python version of the runtime:import platform def lambda_handler(event, context): return {"pythonVersion": platform.python_version()} -
From the same directory, run the following command. The command uses the example image URI from Build and push a runtime image. 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_handlerThe
--platformvalue must match an architecture in the runtime image. -
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:
{"pythonVersion": "3.14.8"} -
To stop the container, press Ctrl+C in the terminal window where the container runs.
If you use your own entrypoint, the RIE doesn't start automatically. To test locally, download the RIE and run your entrypoint under it. You can build the emulator into your image
If your own base image copies /lambda-entrypoint.sh from a Lambda base image, the script starts the RIE when you run the image outside Lambda. The script runs the RIE from /usr/local/bin/aws-lambda-rie, and your image doesn't include the RIE unless you add it. To test locally, add the RIE to the image at that path. Or mount it when you run the container, for example with -v ./aws-lambda-rie:/usr/local/bin/aws-lambda-rie. Lambda doesn't need the RIE in the runtime image.
The RIE doesn't set Lambda environment variables such as LAMBDA_TASK_ROOT. In Lambda, the service sets them, and Lambda base images also set them with ENV. To test a runtime image from your own base image locally, pass the variables when you run the container. For example, pass -e LAMBDA_TASK_ROOT=/var/task to docker run. If your bootstrap uses LAMBDA_RUNTIME_DIR, also pass -e LAMBDA_RUNTIME_DIR=/var/runtime.
Keeping your runtime patched
Lambda doesn't update your runtime image or your runtime versions. You're responsible for patching every component in the runtime image. What you patch depends on your base image:
-
Lambda OS-only base image – Lambda patches the OS. To get the OS patches, rebuild your runtime image from the updated OS-only base image. You patch the language runtime, the RIC, and everything else that you add.
-
Your own base image – You patch every component, including the OS libraries.
After each rebuild, publish the new runtime image as a new runtime version, and update your runtime aliases. We recommend that you rebuild, test, and publish your runtime in an automated pipeline. For more information, see Building a runtime update pipeline.
To make builds reproducible, refer to the base image with a version-specific tag or a digest, and pin the versions of the language runtime and the RIC. Then update the pinned versions to pick up patches. For more information about the trade-offs, see Keeping your runtime patched.
Next steps
After you push your runtime image, continue with the following topics:
-
To create a runtime, see Creating a runtime.
-
To publish your runtime image as a runtime version, see Runtime versions.
-
To roll out the runtime version to functions, see Deploying runtime updates.