sam build: Usage, Options & Common CI Errors

Build the Lambda functions and layers defined in your SAM template.

sam build compiles and packages the functions in an AWS SAM template, resolving dependencies into a .aws-sam build directory ready for local testing or deploy. In CI you often build in a container for Lambda parity.

What it does

sam build reads template.yaml, builds each function/layer per its runtime (installing dependencies, compiling where needed), and writes the artifacts plus a processed template to .aws-sam/build. With --use-container it builds inside a Lambda-like Docker image so native dependencies match the runtime.

Common usage

# Build using the local toolchain
sam build

# Build inside a Lambda-like container (matches the runtime)
sam build --use-container

# Build a single function in parallel
sam build MyFunction --parallel

Common error in CI: runtime not found / native deps mismatch

build fails with "Build Failed ... Runtime pythonX.Y is not supported" (toolchain missing on the runner) or a function works in CI but fails at runtime due to native deps built for the wrong OS. Fix: use sam build --use-container so dependencies are compiled inside the Lambda image (requires Docker on the runner), or install the exact runtime/toolchain the template targets. Pin the runtime in template.yaml and keep the build container image consistent across runs.

Key options

Related guides