AWS SAM CLI

Warnings

• breaking AWS SAM CLI discontinued official support for Python 3.7 as of October 24, 2023. If installed via pip, users on Python 3.7 will be affected. Upgrade your development environment to Python 3.8 or newer.
  Fix: Upgrade your local Python environment to 3.8 or newer for SAM CLI installation. This does not affect the Lambda runtime version you can deploy.
• gotcha Local development and testing features (e.g., `sam build`, `sam local invoke`, `sam local start-api`) require a containerization tool like Docker or Finch to be installed and running on your local machine.
  Fix: Install and start Docker Desktop (or Docker Engine) or Finch on your operating system. SAM CLI will automatically detect and use Finch if Docker is not available (as of v1.137.0+).
• breaking Security vulnerabilities (CVE-2025-3047 and CVE-2025-3048) related to symlink handling during `sam build` with Docker were found. These could allow unauthorized access to host files.
  Fix: Upgrade to AWS SAM CLI v1.134.0 or newer. After upgrading, you *must* re-build your applications using `sam build --use-container` to update symlinks and mitigate the issue. For CVE-2025-3047, use `--mount-symlinks` if you need the previous host-symlink resolution behavior.
• gotcha When using `sam sync` or `sam deploy` across multiple developer environments, explicitly naming resources (e.g., DynamoDB tables) in your `template.yaml` can lead to resource naming conflicts. CloudFormation generates unique names if not specified.
  Fix: Avoid explicitly setting resource names in your `template.yaml`. Instead, let CloudFormation generate names based on the stack name and resource logical ID. Pass generated resource names to your Lambda functions via environment variables, e.g., using `!Ref` or `!GetAtt` in your template.
• gotcha The `.aws-sam/build` directory is an output directory for SAM CLI's build process. Manually modifying files within this directory is not recommended, as changes will be overwritten by subsequent `sam build` commands.
  Fix: Always make changes to your original source code files in your project directory. Run `sam build` to update the `.aws-sam/build` directory with your changes.
• deprecated The `sam package` command's functionality is now implicitly included within `sam deploy`. While `sam package` still works, it's generally recommended to use `sam deploy` directly, which handles both packaging and deployment.
  Fix: Use `sam deploy` directly, which will automatically package your application artifacts before deployment. If specific packaging parameters are needed, they can often be passed to `sam deploy`.

Install

• pip install aws-sam-cli Install via pip
• brew tap aws/tap brew install aws-sam-cli Install via Homebrew (macOS/Linux)

Imports

• AWS SAM CLI

  This is a command-line interface tool and is not typically imported as a Python library in application code.

  The `aws-sam-cli` package provides the `sam` executable for terminal use, not Python modules for direct programmatic import.

Quickstart

This quickstart guides you through initializing a new Python-based 'Hello World' serverless application, building it, testing it locally using `sam local invoke` and `sam local start-api`, and finally deploying it to the AWS Cloud with `sam deploy --guided`. Local testing requires Docker or Finch to be running.

# Initialize a new serverless application (choose 'AWS Quick Start Templates', 'Python 3.x', 'Hello World Example')
sam init --runtime python3.11 --app-template hello-world --name my-sam-app

# Navigate into the project directory
cd my-sam-app

# Build your application (requires Docker or Finch for local container builds)
sam build

# Locally invoke the Lambda function with a sample event
sam local invoke HelloWorldFunction --event events/event.json

# Start a local API Gateway to test your API
sam local start-api

# Deploy your application to AWS Cloud (follow guided prompts)
# Ensure AWS credentials are configured (e.g., via `aws configure` or environment variables)
sam deploy --guided