Introduction

AWS Lambda can run code packaged as a container image, but that does not mean it can run any random Docker image unchanged. Lambda still expects a function-style execution model, so the image must be built for the Lambda runtime contract rather than for a long-lived service process.

What Lambda Actually Supports

When AWS added container image support, it gave developers another packaging format, not a general container hosting platform. A Lambda container still runs inside the Lambda service with the same ideas as a zip-based function:

• the code is invoked by events
• the process is expected to start quickly
• the runtime must know how to receive invocation data and return a response
• the execution environment is short-lived and stateless

That means a normal web container, database container, or background worker image usually cannot just be pushed to Lambda and expected to work. The image needs either:

• an AWS Lambda base image, or
• a custom base image that includes the Lambda Runtime Interface Client

If your container is designed to boot a daemon and sit there listening forever, Lambda is the wrong target. Lambda wants a handler function, not an application server lifecycle that you manage yourself.

Building a Lambda-Compatible Image

The easiest path is to start from an AWS-provided base image. The following example packages a Python function:

1FROM public.ecr.aws/lambda/python:3.12
2
3COPY app.py ${LAMBDA_TASK_ROOT}
4
5CMD ["app.handler"]

And the handler file:

1def handler(event, context):
2    name = event.get("name", "world")
3    return {
4        "statusCode": 200,
5        "message": f"Hello, {name}"
6    }

This works because the base image already includes the runtime integration Lambda needs. When the function is invoked, Lambda starts the container and calls app.handler.

If you want to use your own base image, you must provide the runtime integration yourself. For example:

1FROM python:3.12-slim
2
3RUN pip install awslambdaric
4
5WORKDIR /var/task
6COPY app.py .
7
8ENTRYPOINT ["python", "-m", "awslambdaric"]
9CMD ["app.handler"]

This image is still a Lambda function image. It is not an arbitrary Docker workload. The key part is awslambdaric, which bridges Lambda invocations to your handler.

What Does Not Translate Well

A lot of Docker images are built for patterns that do not fit Lambda:

• containers that expect to expose multiple ports
• services that rely on local persistent disk
• images that need privileged access or Docker-in-Docker
• workloads with very long startup time
• processes that are supposed to stay alive indefinitely

For example, an Nginx image that expects direct client traffic is not a natural Lambda target. You could wrap HTTP handling through Lambda and API Gateway, but at that point you are not really "running Nginx on Lambda" in the usual sense.

Likewise, if your Dockerfile launches a queue worker that polls forever, ECS or AWS Fargate is usually a better fit because those services are meant for continuously running containers.

A Practical Deployment Flow

A typical deployment flow for Lambda container images looks like this:

1. Build the image locally.
2. Push it to Amazon ECR.
3. Create or update a Lambda function that points at that image.

Example commands:

1docker build -t my-lambda-image .
2aws ecr get-login-password --region us-east-1 | \
3  docker login --username AWS --password-stdin 123456789012.dkr.ecr.us-east-1.amazonaws.com
4docker tag my-lambda-image:latest \
5  123456789012.dkr.ecr.us-east-1.amazonaws.com/my-lambda-image:latest
6docker push 123456789012.dkr.ecr.us-east-1.amazonaws.com/my-lambda-image:latest

Then create the function:

1aws lambda create-function \
2  --function-name hello-container \
3  --package-type Image \
4  --code ImageUri=123456789012.dkr.ecr.us-east-1.amazonaws.com/my-lambda-image:latest \
5  --role arn:aws:iam::123456789012:role/lambda-exec-role

The important detail is that Lambda pulls and runs the image within Lambda's restrictions. You are not getting raw container orchestration control.

When to Choose ECS or Fargate Instead

A good rule is simple:

• use Lambda when the container is just packaging for an event-driven function
• use ECS or Fargate when you need a real always-on container

Choose ECS or Fargate if you need custom networking behavior, sidecars, long-running jobs, large local state, or application processes that should stay active across requests.

Lambda container images are most useful when your function has unusual native dependencies, a larger deployment artifact, or a language/runtime setup that is awkward to package as a zip file.

Common Pitfalls

The most common mistake is assuming "container support" means full Docker compatibility. Lambda only supports images that honor the Lambda runtime model.

Another problem is using the wrong entrypoint. If the image does not include the Runtime Interface Client or an AWS Lambda base image, invocations will fail even if the container builds successfully.

Large images are also a problem. Lambda supports sizeable images, but large layers increase cold-start cost and deployment friction. Keep the image lean and remove unnecessary tools.

Finally, developers sometimes move a server application into Lambda without changing architecture. If the workload expects persistent processes, local sockets, or direct inbound network traffic, Lambda will fight that design.

Summary

• Lambda can run container-packaged functions, not arbitrary Docker workloads.
• A Lambda image must use an AWS base image or include the Runtime Interface Client.
• The image still follows Lambda's event-driven handler model.
• Long-running services are usually better on ECS or Fargate.
• Container images are most useful when packaging dependencies is the hard part, not when you need general container hosting.