“SAM Local” means the local testing commands in the AWS Serverless Application Model command line interface (AWS SAM CLI). Install the CLI and a Docker runtime, create a starter project, then build and invoke a Lambda function on your computer.

You do not need an AWS account, AWS CLI, or credentials for the Hello World workflow below. Install the AWS CLI if you later use SAM commands that call AWS; application code that calls AWS services still needs network access and credentials from an approved provider. Local testing can catch code and event-shape problems early, but it does not reproduce every AWS service or prove how a deployed function behaves.

Prerequisites

For the local walkthrough, you need:

  • A supported macOS, Windows, or Linux development machine.
  • The AWS SAM CLI, which provides the sam command.
  • Docker Desktop or another Docker-compatible runtime that is running and available from your terminal. SAM uses containers to run Lambda locally.

The example uses a Python Lambda runtime. As of October 4, 2026, AWS lists Python 3.14 as generally available and Python 3.15 as a public preview. AWS says preview runtimes are not covered by the Lambda SLA or technical support and should not be used in production. Choose a generally available runtime for production, and check the current Lambda runtime table before starting a new project. You can install the matching Python version on your computer for a normal local build, or use sam build --use-container to build in a container with the matching runtime.

An AWS account, AWS CLI, and credentials are unnecessary for a function that only processes its input and returns a result. You will need authorized AWS access if the function itself calls an AWS service, or when you deploy or invoke a function in AWS.

Install the required software

Install and start Docker

Follow the AWS SAM Docker setup guide and the installation steps for your operating system:

  • macOS and Windows: Install Docker Desktop using the Docker installation guide, start it, and allow it to share the folder where your project will live if prompted.
  • Linux: Install Docker Engine using the instructions for your distribution in Docker’s guide. Start the Docker service and give your user permission to run Docker commands. The Amazon Linux 2 and Amazon Linux 2023 commands in AWS’s guide apply to instances running those operating systems; they are not general installation commands for every Linux workstation.

Open a terminal and run docker ps. It should complete without a daemon or permission error. You do not have to fetch a Lambda image by hand; SAM pulls its runtime image when needed. The first build or invocation needs internet access for that download.

Install the AWS SAM CLI

Use the OS-specific installer on AWS’s AWS SAM CLI installation page. The current first-party options are:

  • macOS 13 or later: Download the .pkg for your processor: x86_64 for Intel or arm64 for Apple silicon.
  • Windows: Download and run the 64-bit MSI.
  • Linux: Download the SAM CLI zip for x86_64 or arm64, unzip it, and run its included install program as described in the AWS guide.

Install Git if it is missing on your computer; sam init uses Git to download its starter template.

Open a new terminal after installation and confirm that the command is on your path:

sam --version

Add AWS access only when your work needs it

The AWS CLI is not needed for this local-only example. If you later need to call AWS, install AWS CLI version 2 using the official installation instructions. When your organization uses IAM Identity Center, configure a named SSO profile and sign in for temporary credentials:

aws configure sso --profile dev
aws sso login --profile dev

Use your organization’s assigned account, role, and region. For other account setups, follow the approved federated or role-based login flow. Avoid creating long-lived access keys just to run SAM locally. AWS explains the IAM Identity Center setup and the available AWS CLI authentication methods.

Create and run a local Hello World function

Create the starter project

From a directory where you keep projects, start the interactive initializer:

sam init

Choose AWS Quick Start Templates, then Hello World Example, and select Python with the ZIP package type if prompted. Name the project sam-local-hello-world. The SAM init guide describes the prompts, and AWS’s Hello World tutorial shows the starter files and function name. The template download requires an internet connection.

Open sam-local-hello-world/template.yaml before building. Confirm that the function logical ID is HelloWorldFunction, its event maps a GET request to /hello, and its Runtime is a currently supported Python version. The generated default can change over time; if it is not the runtime you intend to use, update the template and use the same version for a direct local Python build. This walkthrough uses Python 3.14.

Build and invoke the function

Move into the project and build it in a container. This uses the runtime and dependencies declared for the function, so a matching Python installation on your host is not needed:

cd sam-local-hello-world
sam build --use-container

The build writes artifacts under .aws-sam. Now ask SAM to invoke the function with the starter event:

sam local invoke HelloWorldFunction --event events/event.json

For the Hello World starter, the result includes a successful response with a body containing hello world. The --event file supplies the Lambda event; you can edit it to try other inputs. AWS documents the local invoke command and event options.

Try the HTTP endpoint

The starter template also maps an HTTP GET request to the function. Start SAM’s local API server from the project directory:

sam local start-api

Leave that command running. In a second terminal, request the route:

curl http://127.0.0.1:3000/hello

On Windows PowerShell, use Invoke-RestMethod http://127.0.0.1:3000/hello. The response body should contain the Hello World message. Stop the local server with Ctrl+C. See AWS’s guide to testing with sam local start-api for route and event details.

Fix common setup problems

Docker is not running or accessible

If SAM reports that Docker is unavailable, start Docker Desktop or the Docker service, then run docker ps again. On Linux, check that your user has permission to access the Docker socket. On macOS or Windows, check that the project directory is shared with Docker and that the Docker engine has finished starting.

The Python runtime and build environment do not match

For a direct sam build, install the Python version specified by the function’s Runtime. If that version is missing or your dependencies need a Linux-compatible build environment, use sam build --use-container. Container builds need Docker and download a builder image the first time.

The function cannot find AWS credentials

A plain Hello World function does not need AWS credentials. If your handler uses an AWS SDK to call a service, the local process needs network access and credentials with permission for that call. SAM local does not automatically assume the execution role that Lambda would use after deployment. Sign in with your approved temporary-credential flow and select the intended profile, for example with --profile dev. Keep the local permissions limited to the resources the test needs.

What local testing covers

SAM runs your function in a local container and can emulate API Gateway request routing. This is useful for checking handler code, packaging, and sample events without deploying a function. It does not create the AWS services named in your template or fully reproduce their permissions, networking, scaling, event delivery, retries, or managed-service behavior. Any function that makes AWS calls also needs connectivity and credentials for those calls. AWS recommends cloud-based tests to verify service integration and configuration because local tests cannot fully reproduce the deployed environment; see its Lambda testing guide.

After installation, sam init still needs to download its starter template, and SAM needs to fetch builder or runtime images the first time they are used. Once those files and images are cached, a self-contained function can run locally without AWS credentials or an active AWS connection. A function that calls AWS still needs the network and temporary credentials for that service. Treat local results as an early check and verify AWS integrations in an AWS environment before relying on them.

Continue from the local starter

After the first invocation works, read AWS SAM CLI: Local Development Tips for the day-to-day workflow. For unit tests around handler logic, see AWS Lambda Unit Testing Best Practices. When you are ready to automate builds and deployments, continue with AWS SAM Pipelines: Setup Guide.