Skip to content

How do I use container images with Lambda?

3 minute read
0

I want to create AWS Lambda container images with dependencies.

Resolution

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

To deploy your AWS Lambda container images with dependencies, complete the following steps:

  1. Confirm that you have permissions configured for the AWS Identity and Access Management (IAM) user or role that creates the Lambda container images.

  2. Go to the Get Docker page on the Docker website and then choose the Docker Desktop application that meets your requirements. Follow the directions provided to install Docker Desktop.

  3. On your local machine, create one folder with three files: Dockerfile, requirements.txt with libraries, and app.py with import statements.
    Note: Use the latest version of Python for Amazon Elastic Container Registry (Amazon ECR) public registry.
    The following example Dockerfile uses Python 3.14:

    FROM public.ecr.aws/lambda/python:3.14
    # Copy function code
    COPY app.py ${LAMBDA_TASK_ROOT}
    
    # Install the function's dependencies using file requirements.txt
    # from your project folder.
    
    COPY requirements.txt .
    RUN pip3 install -r requirements.txt --target "${LAMBDA_TASK_ROOT}"
    
    # Set the CMD to your handler (could also be done as a parameter override outside of the Dockerfile)
    CMD [ "app.handler" ]

    The following example app.py file includes an example import statement:

    import sys
    def handler(event, context):
        return 'Hello from AWS Lambda using Python' + sys.version + '!'
  4. Build your Docker image with the docker build command and an image name. The following example is a docker build command with a hello-world example:

    docker build -t hello-world .

    Note: If you get an authentication error when pulling from the Amazon ECR public repository, then see Amazon ECR Public troubleshooting.

  5. Start the Docker image with the docker run command.
    The following example is a docker run command with a hello-world example:

    docker run -p 9000:8080 hello-world
  6. Test your application with the Lambda Runtime Interface Emulator (RIE) from AWS on the GitHub website. From a new terminal window, run a curl command to post an event to the following endpoint:

    curl -XPOST "http://localhost:9000/2015-03-31/functions/function/invocations" -d '{}'

    The preceding command invokes the function running in the container image and then returns a response.

  7. To authenticate the Docker CLI to your Amazon ECR registry, run the following get-login-password AWS CLI command:

    aws ecr get-login-password --region your-region | docker login --username AWS --password-stdin 123456789012.dkr.ecr.your-region.amazonaws.com

    Note: Change your-region to your Region and 123456789012 to your account ID.

  8. To create a repository in Amazon ECR, run the following create-repository AWS CLI command:

    aws ecr create-repository --region your-region --repository-name hello-world --image-scanning-configuration scanOnPush=true --image-tag-mutability MUTABLE

    Note: Change repository-name to your repository name and your-region to your AWS Region.

  9. Tag your image to match your repository name with the docker tag command. Then, deploy the image to Amazon ECR with the docker push command.
    Change the account ID and the Region in the command to your account ID and Region.
    This following is an example docker tag command:

    docker tag hello-world:latest 123456789012.dkr.ecr.your-region.amazonaws.com/hello-world:latest

    The following is an example docker push command:

    docker push 123456789012.dkr.ecr.your-region.amazonaws.com/hello-world:latest

    Note: Note: Change 123456789012 to your account ID and your-region to your Region.

  10. With your container image in the Amazon ECR container registry, create and deploy a Lambda function.

For more information, see Create a Lambda function using a container image.

AWS OFFICIALUpdated 3 months ago
4 Comments

For an unauthenticated pull from an Amazon ECR Public repository :

docker logout public.ecr.aws

Troubleshooting reference : https://docs.aws.amazon.com/AmazonECR/latest/public/public-troubleshooting.html

replied 3 years ago

The Sample Dockerfile should be updated

From

COPY requirements.txt . RUN pip3 install -r requirements.txt —target "${LAMBDA_TASK_ROOT}"

To

COPY requirements.txt . RUN pip3 install -r requirements.txt —target "${LAMBDA_TASK_ROOT}"

replied 3 years ago

Thank you for your comment. We'll review and update the Knowledge Center article as needed.

AWS
EXPERT

replied 3 years ago

This article was reviewed and updated on 2026-08-18.

EXPERT

replied 3 months ago