Registry / aws / aws-sam-translator

aws-sam-translator

library1.113.0pypypi✓ verified 25d ago

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.

aws devops

pip install aws-sam-translator

github ↗package ↗

INSTALL

IMPORT

SIG · AWS-SAM-TRANSLATOR

aws-sam-translator

awspythonv1.113.0

Install

7.3s avg

Import

1442ms

Disk

68MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.113.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 1.480s · 69.1MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 7.3s · import 1.404s · 68MB

68MB installed

● package 68MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Translator

✓ from samtranslator.translator.translator import Translator

InvalidDocumentException

✓ from samtranslator.public.exceptions import InvalidDocumentException

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}")

Debug

Known issues

breakingInstalling `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.

affects: All versions when combined with pip-installed `aws-sam-cli`

gotchaThe `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.

affects: All versions

gotchaThe `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`.

affects: All versions

gotchaThe 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.

affects: Prior to 1.99.0, potentially other versions with specific `pydantic` releases.

gotchaThe `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.

affects: All versions (environment-dependent)

breakingThe 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`.

affects: All versions where PyYAML is not installed

Errors

Common errors & fixes

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.

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: Can't find exact resource information with given <stack-name>. Please provide full resource ARN or --stack-name to resolve the ambiguity.

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: Failed to create managed resources: Unable to locate credentials

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: FileNotFoundError

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: Running AWS SAM projects locally requires Docker. Have you got it installed?

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.

Upgrade

Version history

1.113.0latest on PyPI · released Aug 24, 2026

Audit

Dependencies

boto3requiredRequired for AWS interactions, often specified with version constraints.

jsonschemarequiredUsed for validating SAM template against its schema.

pydanticrequiredUsed for data validation and parsing, specific versions can cause conflicts.

typing-extensionsrequiredProvides backports of typing features for broader Python version compatibility.

PyYAMLoptionalCommonly used for parsing SAM templates (YAML format), though not a direct runtime dependency within `samtranslator` core.

Agent activity

17 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/awslabs/serverless-application-model ↗

packagehttps://pypi.org/project/aws-sam-translator/ ↗