AWS SAM Translator

1.108.0 verified Tue May 12 auth: no python install: verified quickstart: stale

AWS SAM Translator is a Python library responsible for transforming AWS Serverless Application Model (SAM) templates into standard AWS CloudFormation templates. It is a core component used by the AWS SAM CLI and maintains a rapid release cadence, with updates often reflecting new SAM specification features and CloudFormation resource support. The current version is 1.108.0.

pip install aws-sam-translator

Common errors

error ERROR: pip's dependency resolver does not currently take into account all the packages that are installed. This behaviour is the source of the following dependency conflicts. aws-sam-cli 1.58.0 requires aws-sam-translator==1.51.0, but you have aws-sam-translator 1.58.0 which is incompatible. ↓

cause This error occurs when the installed version of aws-sam-translator is incompatible with the version required by aws-sam-cli.

fix

Ensure that the versions of aws-sam-cli and aws-sam-translator are compatible. You can do this by installing the aws-sam-cli using the native package installer, which manages dependencies automatically. Alternatively, if using pip, install the AWS SAM CLI into a virtual environment to avoid dependency conflicts. For more information, see the AWS SAM CLI troubleshooting guide.

error Error: Can't find exact resource information with given <stack-name>. Please provide full resource ARN or --stack-name to resolve the ambiguity. ↓

cause This error occurs when the 'sam remote invoke' command is run without providing the --stack-name option, leading to ambiguity in identifying the resource.

fix

Provide the --stack-name option when running the 'sam remote invoke' command. For example: 'sam remote invoke --stack-name sam-app'. For more details, refer to the AWS SAM CLI troubleshooting guide.

error Error: Failed to create managed resources: Unable to locate credentials ↓

cause This error indicates that AWS credentials have not been set up, preventing the AWS SAM CLI from making AWS service calls.

fix

Set up AWS credentials to enable the AWS SAM CLI to make AWS service calls. For instructions, see the AWS SAM CLI troubleshooting guide.

error Error: FileNotFoundError ↓

cause This error can occur on Windows when the AWS SAM CLI interacts with file paths that exceed the Windows maximum path length limitation.

fix

Enable long paths in Windows 10, version 1607, and later to resolve this issue. For guidance, see the AWS SAM CLI troubleshooting guide.

error Error: Running AWS SAM projects locally requires Docker. Have you got it installed? ↓

cause This error occurs when Docker is not properly installed, which is required to test AWS SAM applications locally.

fix

Install Docker for your development host to enable local testing of AWS SAM applications. For more information, see the AWS SAM CLI troubleshooting guide.

Warnings

breaking Installing `aws-sam-translator` directly via pip can lead to dependency conflicts if `aws-sam-cli` is also installed via pip, as `aws-sam-cli` often depends on a specific, fixed version of `aws-sam-translator`. ↓

fix AWS recommends installing `aws-sam-cli` using its native package installers (e.g., Homebrew, MSI, apt) to avoid these conflicts. If using pip, ensure `aws-sam-cli` and `aws-sam-translator` versions are compatible.

gotcha The `CodeUri` property in `AWS::Serverless::Function` cannot be transformed if it points to a local directory when using the `aws-sam-translator` library directly. It expects S3 URIs or inline code for translation. ↓

fix Ensure `CodeUri` references an S3 bucket path or use `InlineCode` for direct translation with the library. Local build artifacts (e.g., from `sam build`) are handled by the SAM CLI, not by the raw translator library.

gotcha The `aws-sam-translator` library is a core component for *translating* SAM templates to CloudFormation, but it does not *deploy* them. Users often confuse the library's role with that of the `aws-sam-cli`, which provides build, local testing, and deployment capabilities. ↓

fix Understand that `aws-sam-translator` generates CloudFormation. Deployment of this CloudFormation output requires further steps, typically via `aws-sam-cli deploy` or `aws cloudformation deploy`.

gotcha The library has had past issues with `pydantic` version compatibility (e.g., `AttributeError: module 'pydantic.v1' has no attribute 'error_wrapper'`). While fixed, this indicates a sensitivity to its `pydantic` dependency. ↓

fix Always install `aws-sam-translator` with its specified `pydantic` version ranges or ensure your environment satisfies its dependency constraints. Refer to `requirements.txt` in the GitHub repository or PyPI metadata for the exact compatible `pydantic` versions.

gotcha The `ModuleNotFoundError: No module named 'yaml'` indicates that the `PyYAML` package, which provides the `yaml` module for parsing and emitting YAML, is not installed in the environment. Scripts processing SAM/CloudFormation templates often require this package. ↓

fix Install the `PyYAML` package using pip: `pip install PyYAML`. Ensure this is done in the correct Python environment or virtual environment where your script or the library is being executed.

breaking The script failed because the `yaml` module was not found. This typically means the `PyYAML` package, which provides the `yaml` module, was not installed in the environment where the script was executed. ↓

fix Ensure `PyYAML` is installed in the Python environment. Add `PyYAML` to your project's `requirements.txt` file (e.g., `PyYAML==6.0.1`) and install it using `pip install -r requirements.txt` or `pip install pyyaml`.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 1.36s 68.0M

3.10 alpine (musl) - - 1.39s 67.7M

3.10 slim (glibc) wheel 7.5s 1.04s 67M

3.10 slim (glibc) - - 0.97s 67M

3.11 alpine (musl) wheel - 1.81s 72.6M

3.11 alpine (musl) - - 1.95s 72.2M

3.11 slim (glibc) wheel 6.3s 1.65s 72M

3.11 slim (glibc) - - 1.48s 71M

3.12 alpine (musl) wheel - 1.90s 63.7M

3.12 alpine (musl) - - 1.89s 63.4M

3.12 slim (glibc) wheel 5.1s 1.87s 63M

3.12 slim (glibc) - - 1.78s 63M

3.13 alpine (musl) wheel - 1.51s 63.5M

3.13 alpine (musl) - - 1.48s 63.0M

3.13 slim (glibc) wheel 4.8s 1.52s 63M

3.13 slim (glibc) - - 1.51s 62M

3.9 alpine (musl) wheel - 1.15s 67.5M

3.9 alpine (musl) - - 1.23s 67.2M

3.9 slim (glibc) wheel 8.5s 1.26s 67M

3.9 slim (glibc) - - 1.06s 66M

Imports

Translator

from samtranslator.translator.translator import Translator

InvalidDocumentException

from samtranslator.public.exceptions import InvalidDocumentException

Quickstart stale last tested: 2026-04-24

This example demonstrates how to parse a SAM template string, initialize the `Translator` class, and convert the SAM template into a standard CloudFormation template. In a real application, `managed_policy_map` and `globals` would be populated based on the SAM template's contents or external configuration.

import json
import yaml
from samtranslator.translator.translator import Translator
from samtranslator.public.exceptions import InvalidDocumentException

sam_template_str = """
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: A simple SAM template for testing

Resources:
  MyFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: app.lambda_handler
      Runtime: python3.9
      CodeUri: s3://my-bucket/my-code.zip
      MemorySize: 128
      Timeout: 30
      Events:
        Api:
          Type: Api
          Properties:
            Path: /hello
            Method: GET
"""

# Load SAM template (YAML or JSON)
sam_template = yaml.safe_load(sam_template_str)

# Initialize the translator. 
# managed_policy_map is usually populated from AWS::Serverless::Function/StateMachine policies
# and globals from the Globals section of the template.
translator = Translator(
    sam_template=sam_template,
    managed_policy_map={},
    globals={}
)

try:
    # Translate the SAM template to CloudFormation
    cloudformation_template = translator.translate()
    print("Translated CloudFormation Template:")
    print(json.dumps(cloudformation_template, indent=2))
except InvalidDocumentException as e:
    print(f"Error translating template: {e}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")