Skip to main content

CPU Architecture

Our cookiecutter project defaults to building a Linux container image targeting the arm64 architecture vs the traditional x86_64 cpu type. Applications that use arm64 (AWS Graviton2 processor) can achieve significantly better price and performance than the equivalent workloads running an on x86_64 architecture.

Deploying arm64 applications is still a relatively new process and requires a few special considerations from local development to your CI/CD tooling. AWS Lambda makes this easy using the Architectures setting of the AWS::Lambda::Function CloudFormation resource. However, here are a few things you should know.

Docker Images

Most base Docker images are now build for multiple platforms. Consider the following Dockerfile:

FROM ruby:3.2-bullseye

How does Docker know which platform to use? The anwser is to use the default platform of the host. If you are on a M1 or M2 Mac, arm64 would be the platform used. Which platforms are in a specific base image? We can find out using the docker manifest command. For example:

$ docker manifest inspect ruby:3.2 | grep arch
"architecture": "amd64",
"architecture": "arm64",
$ docker manifest inspect | grep arch
"architecture": "amd64",
"architecture": "arm64",

All the images in our starter project are multi-platform. This means any host can be used for development. Your computer, Codespaces, etc will use the proper platform image variants.

Deployment Gotchas

Though there are numerous ways to deploy containers using techniques such as emulation. However, we recommend you following one simple rule. Matching your “Development Host OS/Arch” to that of your target “Deployment Host OS/Arch” provides the least development friction. Use a CI/CD platform that matches your deployment target.


Currently GitHub Actions does not support native arm64 runners. They are working to add this feature.

Our Quick Start guide has your first deploy happening from your local machine. Since we default to arm64 this should work fine if you are on a Mac with Apple Silicon. But what if you are on a Windows or Linux system with an x86_64 architecture? Your function will not work since your application's system dependences (like mysq2) will be compiled for the wrong architecture. Depending on your needs, you may have to switch back to x86_64 as described below.

For more information on deployments, see our How Lamby Works guide.

Switching to x86_64

Based off the current state of our cookiecutter project, here are the changes required to switch to a x86_64 deployment target. First, change your CircleCI workflows default machine from `arm.large`` to a standard large.

default-machine: &default-machine
image: ubuntu-2204:current
docker_layer_caching: true
- resource_class: arm.large
+ resource_class: large

Now open up your AWS SAM serverless template.yaml file, find the Globals section and change your Architecture property from arm64 to x86_64.

- - arm64
+ - x86_64