Skip to main content
AWS Lambda supports packaging functions as Docker container images and deploying them via Amazon ECR using standard container tooling. Using container images as a packaging format is helpful because the size limit is higher at 10 GB. The only caveat is that running a container image on AWS Lambda demands meeting certain requirements. See also AWS docs and AWS Lambda Python example This tutorial demonstrates building a custom Python app using a multi-stage Dockerfile to run on AWS Lambda. The build stage uses the Minimus python:latest-dev image because it requires the package installer pip.  The runtime uses the fully distroless production image to achieve the most secure app.  Learn more about multi-stage-builds

​
What this guide demonstrates:

  • Minimus Python images can run on AWS Lambda
  • Amazon Linux is not required
  • Non-root execution is supported
  • Buildx defaults must be overridden

​
Prerequisites

You will need:
  • Access to an AWS account
  • Permission to:
    • Create ECR repositories
    • Push images to ECR
    • Create and invoke Lambda functions
      • Access to create or use a role for the function
    • Read CloudWatch logs

​
Process

1

Create Python app

Create a Python app app.py:
app.py
import sys
import os

def handler(event, context):
    return {
        "ok": True,
        "python": sys.version,
        "cwd": os.getcwd(),
        "uid": os.getuid(),
        "event": event,
    }
2

Create Dockerfile

First authenticate to the Minimus registry so the images can be pulled. Learn moreSave the following Dockerfile (venv is short for virtual environment):
Dockerfile
# === Build Stage ===

FROM reg.mini.dev/python:latest-dev AS builder

WORKDIR /var/task

# Create an isolated venv for runtime dependencies (including awslambdaric)

RUN python -m venv /opt/venv

ENV PATH="/opt/venv/bin:\$PATH"

# Install the Lambda Runtime Interface Client (RIC) into the venv
# Add other dependencies if relevant (requirements.txt)

RUN pip install --no-cache-dir awslambdaric

# === Runtime Stage ===

FROM reg.mini.dev/python:latest

# Lambda expects code in /var/task

WORKDIR /var/task

COPY [app.py](http://app.py) .

# Copy the pre-built venv from the builder stage

COPY --from=builder /opt/venv /opt/venv

# Use venv python and packages at runtime

ENV PATH="/opt/venv/bin:\$PATH"

ENV HOME=/home/python

USER 1000

# Lambda container contract:
# ENTRYPOINT starts the runtime interface client
# CMD names the handler

ENTRYPOINT ["python", "-m", "awslambdaric"]

CMD ["app.handler"]
3

Create an ECR repository

Create an ECR repository. Official Guide from AWS  In the AWS Console:
  1. Go to Elastic Container Registry (ECR)
  2. Create a private repository. For this guide, we assume you named it: minimus-lambda-example
  3. Note the full repository URI, for example: 123456789012.dkr.ecr.eu-north-1.amazonaws.com/minimus-lambda-example
4

Authenticate to your default registry

Authenticate the Docker CLI to your default registry so the docker command can push and pull images with Amazon ECR. Official Guide from AWS
aws ecr get-login-password --region eu-north-1 \
  | docker login --username AWS --password-stdin \
    123456789012.dkr.ecr.eu-north-1.amazonaws.com
Replace the example URI in the above command with your own before running the command.
5

Build and push the image

Build the image using buildx. Buildx is an extended Docker build command that uses BuildKit under the hood. It is used for advanced builds involving multi-architecture, remote push, and more.
docker buildx build \
  --platform linux/arm64 \
  --provenance=false \
  --sbom=false \
  -t 123456789012.dkr.ecr.eu-north-1.amazonaws.com/minimus-lambda-example:lambda-arm64 \
  --push \
  .
6

Create the Lambda function

In the AWS Console:
  1. Go to Lambda
  2. Click Create function
  3. Select container image
  4. Select minimus-lambda-example:lambda-arm64
  5. Set Architecture to arm64
  6. Create or select an execution role
  7. Create the function
7

Invoke via AWS CLI

Create a test event:
echo '{"hello":"lambda"}' > event.json
Invoke the function:
aws lambda invoke \
  --function-name minimus-lambda-example \
  --payload file://event.json \
  --cli-binary-format raw-in-base64-out \
  --region eu-north-1 \
  response.json
View the response:
cat response.json
8

Invoke via AWS console

  1. Open the Lambda function
  2. Click Test
  3. Create a new test event:
{

  "hello": "lambda"

}
  1. Invocation type: Synchronous
  2. Click Test

​
Required Buildx flags

Lambda requires a single-architecture image manifest, not an OCI index with attestations. Docker Buildx adds provenance and SBOM attestations by default, which results in the pushed image becoming an OCI image index containing an extra attestation manifest (often shown as unknown/unknown platform). Since AWS Lambda does not support this image format, it is necessary to add the following Buildx flags:
  • --provenance=false
  • --sbom=false
If the above flags are omitted, Lambda creation fails with the error: The image manifest, config or layer media type is not supported.
Last modified on February 4, 2026