Building a custom runtime on AWS Lambda
profile picture Sandeep Kumar P
4 min read Dec 7, 2023

Building a custom runtime on AWS Lambda

What is it?

AWS Lambda provides managed runtimes for Node.js, Python, Java, Ruby, Go and .NET. You can get the exact runtime versions by creating a new lambda function in the aws console. AWS realises that there could be some specifications beyond the provided runtimes and release an option to create a custom runtime. What is it? It’s a custom docker image which allows you to create and control a bootstrap file (we will get to it shortly), thereby enabling you to create a lambda on any runtime configuration that you require. Check out the official AWS Documentation here.

They offer unparalleled flexibility and customization, allowing developers to create runtime environments tailored to the unique needs of their applications. Custom runtimes also fill the gap when standard runtimes don’t support specific programming languages or dependencies.

To understand the logical flow of events and behind the screen events of a lambda runtime, make sure you check out this blog.

What happens inside an AWS Lambda

The files involved in a custom runtime

For the sanity of this blog, we will consider building a custom python3.11 environment. Let’s dive into the technical aspects. Here is a sample folder structure of how a custom runtime lambda will look like

Lambda Folder 
-– | bootstrap
-– | Dockerfile
-– |
-– | requirements.txt

1. bootstrap

The bootstrap is one of the, if not the most critical aspect of a custom runtime. Why? Because it is the entry point of your lambda function, initialises the handler function, and handles the interaction with the lambda being executed to transact between the caller and the receiver.

Flow of events

Lambda is invoked from an the client from an HTTP client >>> The bootstrap code continuously polls for the next lambda >>> When an invocation event is received, the bootstrap file takes control of the next step and in our case, invokes the handler function >>> Bootstrap waits for the lambda handler execution to complete >>> Sends the response of the lambda invocation.

Bootstrap file code

Key Concepts

Lambda Runtime API - The HTTP API enabling custom runtimes to poll for lambda executions and post the results corresponding to the invocation. Bootstrap file language restrictions - The bootstrap file can be written on any language as long as the docker file can execute the file Response Type - You can either have a regular response runtime or a streaming response runtime, based on your requirement.

2. Dockerfile

As the file states, it’s a docker file that creates the docker image required for your custom runtime. The docker file starts with choosing a base image - Lambda Custom Runtimes can be built on 2 base images provided by AWS. The “al2” that runs on Amazon Linux 2 or “alami” that runs on Amazon Linux. After that you need to install the required packages / libraries required for the bootstrap file and the custom runtime. The lambda exposes certain environment variables like LAMBDA_RUNTIME_DIR , LAMBDA_TASK_ROOT, etc. The bootstrap file should be copied to LAMBDA_RUNTIME_DIR whereas the lambda handler function and all the dependencies need to be copied to LAMBDA_TASK_ROOT.

Key Concepts

  • Entire Variables List here - AWS Lambda Environment Variables
  • If you are planning to build a python runtime, make sure you install the SSL library as shown in the sample. Learnt it the hard way that there is a dependency issue with the base lambda image and python 3.10 and above runtimes,
  • Lambda base images - To run a custom runtime which enables you to have control over the bootstrap file you need to choose the “al2” or the “alami” image, if you choose any runtime base image (python, nodejs, etc) you will not have control over the bootstrap file.
  • Lambda base image links - AWS Lambda Base Images

3. and requirements.txt

The is the actual lambda runtime file that gets executed. And the requirements.txt holds all the required libraries. Since the blog walks on a python custom runtime sample, the files follow the python conventions.



In a nutshell, Lambda custom runtimes allow you to have a flexible and personalised serverless experience. It lets you use languages and tools not covered by standard AWS Lambda runtimes and adapt to the ever-changing tech landscape.

Custom runtimes gets you under the hood of lambda, thanks to the bootstrap file and Dockerfile. The bootstrap file is your Lambda function’s conductor, making sure everything runs smoothly, while the Dockerfile sets up the stage. With this knowledge, you’re ready to embark on your custom runtime adventure, crafting unique solutions and future-proofing your applications. Get out there and start building amazing serverless applications that match your needs perfectly. Happy coding!

Application Modernization Icon

Innovate faster, and go farther with serverless-native application development. Explore limitless possibilities with AntStack's serverless solutions. Empowering your business to achieve your most audacious goals.

Build with us



Share this blog

Your Digital Journey deserves a great story.

Build one with us.

Recommended Blogs

Cookies Icon

These cookies are used to collect information about how you interact with this website and allow us to remember you. We use this information in order to improve and customize your browsing experience and for analytics and metrics about our visitors on this website.

If you decline, your information won’t be tracked when you visit this website. A single cookie will be used in your browser to remember your preference not to be tracked.

Build With Us