With a non-AWS base image such as Alpine or Debian, you must add a runtime interface client yourself and you own every layer of the operating system and language runtime. AWS provides base images and publishes updates, but a custom image is only as current as your own rebuild schedule.
What AWS documents
AWS describes three ways to build a Lambda container image: an AWS base image, an AWS OS-only base image, or a non-AWS base image. For the last, Lambda accepts any image that conforms to the Docker image manifest V2 schema 2 or the OCI specification v1.0.0 and up, up to 10 GB uncompressed including all layers. AWS states the image must include a runtime interface client for your language so it can talk to Lambda. It supplies open-source clients for Node.js, Python, Java, .NET, Go, Ruby and Rust, and says that if no client exists for your language you must create your own.
What you now own
| Item | AWS base image | Non-AWS base image |
|---|---|---|
| Language runtime | Preloaded | You install it |
| Runtime interface client | Preloaded | You add it |
| OS packages | AWS publishes image updates | You rebuild when upstream publishes fixes |
| Image provenance | AWS | Your chosen source and your pipeline |
None of this is wrong. Many organizations require a standard hardened image across every service. It is a trade: consistency with your platform versus AWS-maintained defaults.
Requirements that apply to any image
AWS lists a few that affect security reviews. The image must run on a read-only file system, with a writable /tmp of 512 MB to 10,240 MB. Lambda defines a default Linux user with least-privileged permissions, so you do not need a USER line, and your application should not rely on files other users are restricted from running. Lambda supports only Linux-based images and does not support multi-architecture container images for a single function.
A checklist for owning a custom base
- Pin the base by digest, not just a tag, so a build is repeatable.
- Record where the base comes from and who approved it.
- Pin the runtime interface client version and track its releases like any dependency.
- Rebuild on a schedule, for example weekly, plus on any critical advisory.
- Scan the final image, not only the Dockerfile, including OS packages.
- Keep the image small. Multi-stage builds help, and AWS suggests them to reduce activation time and recommends keeping the image manifest under 25,400 bytes for performance.
- Test on a read-only file system before deploying.
Where the work usually slips
The runtime interface client is the piece teams forget. It is a dependency inside your image with its own release stream, and it runs with your function's permissions. Put it in the inventory.
The other common slip is a long gap between rebuilds. A function that has not been redeployed keeps its old image, however much upstream has moved on. See rebuilding after an AWS base image update.
Try it yourself
Open the container image scan demo and look at how findings split between OS packages and application packages. A custom base image puts more of that list on you.
Click through it at your own pace, or open it full screen.
Where Safeguard fits
Safeguard scans container images for vulnerable packages and produces an SBOM, so a custom base image gets the same inventory as application code. Free scan: gold.safeguard.sh/scan.
Quick check
Do I need to add anything to an Alpine image for Lambda?
Yes. AWS says a non-AWS base image must include a runtime interface client for your language.
Can one Lambda image target two CPU architectures?
No. AWS says the image you build for a function must target one architecture, and multi-architecture container images are not supported for a function.
Sources
Last reviewed: 19 October 2026.
