{"id":611,"library":"aws-sam-translator","title":"AWS SAM Translator","description":"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.","status":"active","version":"1.108.0","language":"python","source_language":"en","source_url":"https://github.com/aws/serverless-application-model","tags":["aws","sam","serverless","cloudformation","template","translator"],"install":[{"cmd":"pip install aws-sam-translator","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required for AWS interactions, often specified with version constraints.","package":"boto3","optional":false},{"reason":"Used for validating SAM template against its schema.","package":"jsonschema","optional":false},{"reason":"Used for data validation and parsing, specific versions can cause conflicts.","package":"pydantic","optional":false},{"reason":"Provides backports of typing features for broader Python version compatibility.","package":"typing-extensions","optional":false},{"reason":"Commonly used for parsing SAM templates (YAML format), though not a direct runtime dependency within `samtranslator` core.","package":"PyYAML","optional":true}],"imports":[{"symbol":"Translator","correct":"from samtranslator.translator.translator import Translator"},{"symbol":"InvalidDocumentException","correct":"from samtranslator.public.exceptions import InvalidDocumentException"}],"quickstart":{"code":"import json\nimport yaml\nfrom samtranslator.translator.translator import Translator\nfrom samtranslator.public.exceptions import InvalidDocumentException\n\nsam_template_str = \"\"\"\nAWSTemplateFormatVersion: '2010-09-09'\nTransform: AWS::Serverless-2016-10-31\nDescription: A simple SAM template for testing\n\nResources:\n  MyFunction:\n    Type: AWS::Serverless::Function\n    Properties:\n      Handler: app.lambda_handler\n      Runtime: python3.9\n      CodeUri: s3://my-bucket/my-code.zip\n      MemorySize: 128\n      Timeout: 30\n      Events:\n        Api:\n          Type: Api\n          Properties:\n            Path: /hello\n            Method: GET\n\"\"\"\n\n# Load SAM template (YAML or JSON)\nsam_template = yaml.safe_load(sam_template_str)\n\n# Initialize the translator. \n# managed_policy_map is usually populated from AWS::Serverless::Function/StateMachine policies\n# and globals from the Globals section of the template.\ntranslator = Translator(\n    sam_template=sam_template,\n    managed_policy_map={},\n    globals={}\n)\n\ntry:\n    # Translate the SAM template to CloudFormation\n    cloudformation_template = translator.translate()\n    print(\"Translated CloudFormation Template:\")\n    print(json.dumps(cloudformation_template, indent=2))\nexcept InvalidDocumentException as e:\n    print(f\"Error translating template: {e}\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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`.","severity":"breaking","affected_versions":"All versions when combined with pip-installed `aws-sam-cli`"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"Prior to 1.99.0, potentially other versions with specific `pydantic` releases."},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions (environment-dependent)"},{"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`.","message":"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.","severity":"breaking","affected_versions":"All versions where PyYAML is not installed"}],"env_vars":null,"last_verified":"2026-05-12T16:41:31.247Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"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.","cause":"This error occurs when the installed version of aws-sam-translator is incompatible with the version required by aws-sam-cli.","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."},{"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.","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.","error":"Error: Can't find exact resource information with given <stack-name>. Please provide full resource ARN or --stack-name to resolve the ambiguity."},{"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.","cause":"This error indicates that AWS credentials have not been set up, preventing the AWS SAM CLI from making AWS service calls.","error":"Error: Failed to create managed resources: Unable to locate credentials"},{"fix":"Enable long paths in Windows 10, version 1607, and later to resolve this issue. For guidance, see the AWS SAM CLI troubleshooting guide.","cause":"This error can occur on Windows when the AWS SAM CLI interacts with file paths that exceed the Windows maximum path length limitation.","error":"Error: FileNotFoundError"},{"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.","cause":"This error occurs when Docker is not properly installed, which is required to test AWS SAM applications locally.","error":"Error: Running AWS SAM projects locally requires Docker. Have you got it installed?"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":"1.109.0","install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":1.36,"mem_mb":27.4,"disk_size":"68.0M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.39,"mem_mb":27.3,"disk_size":"67.7M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":7.5,"import_time_s":1.04,"mem_mb":27.4,"disk_size":"67M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.97,"mem_mb":27.3,"disk_size":"67M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":1.81,"mem_mb":29.8,"disk_size":"72.6M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.95,"mem_mb":29.7,"disk_size":"72.2M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":6.3,"import_time_s":1.65,"mem_mb":29.9,"disk_size":"72M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.48,"mem_mb":29.7,"disk_size":"71M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":1.9,"mem_mb":29.4,"disk_size":"63.7M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.89,"mem_mb":29.3,"disk_size":"63.4M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":5.1,"import_time_s":1.87,"mem_mb":29.4,"disk_size":"63M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.78,"mem_mb":29.3,"disk_size":"63M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":1.51,"mem_mb":28.6,"disk_size":"63.5M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.48,"mem_mb":28.5,"disk_size":"63.0M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":4.8,"import_time_s":1.52,"mem_mb":28.6,"disk_size":"63M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.51,"mem_mb":28.5,"disk_size":"62M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":1.15,"mem_mb":26.9,"disk_size":"67.5M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.23,"mem_mb":26.8,"disk_size":"67.2M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":8.5,"import_time_s":1.26,"mem_mb":26.9,"disk_size":"67M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.06,"mem_mb":26.8,"disk_size":"66M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}