Install & Compatibility
Where this runs
tested against v1.3.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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.236s · 21.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.8s · import 0.220s · 22MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
flip
✓ from cfn_flip import flip
General conversion function, attempts to detect input format.
to_yaml
✓ from cfn_flip import to_yaml
Converts a JSON or YAML string to YAML format.
to_json
✓ from cfn_flip import to_json
Converts a JSON or YAML string to JSON format.
This quickstart demonstrates how to use the `to_yaml` and `to_json` functions to convert CloudFormation templates between JSON and YAML formats within a Python script. It shows conversion from a JSON string to YAML and from a YAML string to JSON.
from cfn_flip import to_yaml, to_json
json_template = '''
{
"AWSTemplateFormatVersion": "2010-09-09",
"Description": "Example JSON template",
"Resources": {
"MyS3Bucket": {
"Type": "AWS::S3::Bucket",
"Properties": {
"BucketName": "my-unique-example-bucket"
}
}
}
}
'''
yaml_output = to_yaml(json_template)
print("--- JSON to YAML ---")
print(yaml_output)
yaml_template = '''
AWSTemplateFormatVersion: '2010-09-09'
Description: Example YAML template
Resources:
MyLambdaFunction:
Type: AWS::Lambda::Function
Properties:
Handler: index.handler
Role: !GetAtt MyLambdaRole.Arn
Code:
S3Bucket: my-code-bucket
S3Key: my-code.zip
Runtime: python3.9
'''
json_output = to_json(yaml_template)
print("\n--- YAML to JSON ---")
print(json_output)
cfn-flip --version
Debug
Known issues
deprecatedThe command-line interface (CLI) of `cfn-flip` is officially deprecated. Users are advised to use `rain fmt` from the `aws-cloudformation/rain` project for CLI-based template formatting and conversion instead.fixMigrate CLI usage from `cfn-flip` to `rain fmt`. For example, `cfn-flip -j template.yaml` becomes `rain fmt template.yaml --json`.
affects: All versions (deprecation announced in 1.3.0 README)
gotchaConverting JSON templates to YAML using `cfn-flip`'s default shorthand syntax for intrinsic functions (e.g., `!Ref`, `!GetAtt`) can unexpectedly cause CloudFormation Change Sets to propose resource replacement instead of modification, even if no logical change occurred. This can lead to unintended downtime or data loss.fixWhen converting from JSON to YAML, consider using the `--long` option with the `cfn-flip` CLI (if still using it) or manually ensuring long-form function syntax in the YAML output to avoid unexpected resource replacements. Thoroughly review CloudFormation Change Sets before execution after conversion.
affects: All versions
gotchaWhen converting a CloudFormation template from YAML to JSON format using `cfn-flip`, any comments present in the original YAML template will be lost in the resulting JSON output, as JSON does not natively support comments.fixBe aware of this limitation and ensure important contextual information is not solely reliant on YAML comments if JSON conversion is part of your workflow. Consider documenting templates externally or retaining the YAML source if comments are critical.
affects: All versions
gotcha`cfn-flip` uses a YAML parser that is more strict than the AWS CloudFormation service itself. This means that `cfn-flip` might flag certain YAML syntax issues (e.g., using tabs instead of spaces for indentation) as errors, even though CloudFormation might accept them.fixAdhere strictly to the YAML specification (e.g., use spaces for indentation, not tabs) to ensure compatibility with `cfn-flip` and other YAML tooling like `cfn-lint`. This generally leads to more robust and portable templates.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'cfn_flip'
This error occurs when the Python interpreter cannot find the `cfn_flip` package, often due to it not being installed, or an incorrect import name being used (the package is `cfn_flip` with an underscore, while the CLI is `cfn-flip` with a hyphen), or `cfn_tools` module not being found which is part of `cfn_flip`.
fixEnsure the `cfn-flip` package is installed via pip: `pip install cfn-flip`. When importing in Python, use `import cfn_flip` or `from cfn_flip import flip` (for the main conversion function) or `from cfn_flip import cfn_tools` if specifically trying to access `cfn_tools`.
cfn-flip: command not found
This error indicates that the `cfn-flip` command-line tool is not in your system's PATH, or it was not installed correctly as an executable.
fixFirst, ensure `cfn-flip` is installed: `pip install cfn-flip`. If it's installed but not found, check your Python environment's script directory and add it to your system's PATH. On Linux/macOS, it's often in `~/.local/bin` or a similar directory for your Python installation. If using a virtual environment, ensure it's activated.
while scanning for the next token found character '\t' that cannot start any token
This is a common YAML parsing error, specifically indicating that tabs (`\t`) are being used for indentation in a CloudFormation template instead of spaces. YAML strictly requires spaces for indentation.
fixReplace all tab characters with spaces in your YAML CloudFormation template. Most text editors have a feature to convert tabs to spaces automatically. For example, in VS Code, you can often find 'Convert Indentation to Spaces' in the command palette.
Template error: every value of the context object of every Fn::Sub object must be a string or a function that returns a string.
This error typically arises when using `cfn-flip`'s `clean` functionality, particularly when it attempts to convert `Fn::Join` constructs that include `AWS::NoValue` into `Fn::Sub` functions. `Fn::Sub` does not handle `AWS::NoValue` gracefully in its context object.
fixAvoid using the `--clean` flag with templates that contain `Fn::Join` alongside `AWS::NoValue`. If programmatic cleaning is necessary, consider implementing a custom cleanup logic that specifically handles `Fn::Join` with `AWS::NoValue` or preprocess the template to remove `AWS::NoValue` before passing it to `cfn-flip`'s cleaning function. Alternatively, consider refactoring your CloudFormation template to avoid `Fn::Join` with `AWS::NoValue` where `cfn-flip`'s `clean` option would interfere.
ERROR: Could not find a version that satisfies the requirement cfn-flip
This installation error occurs when `pip` cannot find a suitable version of `cfn-flip` that is compatible with your current Python environment or due to issues with pip's cache or index.
fixTry upgrading `pip` and `setuptools`: `pip install --upgrade pip setuptools`. If the issue persists, ensure you are using a supported Python version (Python 2.7 or >=3.5) and clear pip's cache: `pip cache purge`. You can also try specifying an older, known-to-work version of `cfn-flip` if there are compatibility concerns with the latest: `pip install cfn-flip==1.3.0`.
Upgrade
Version history
1.3.0latest on PyPI · released Oct 7, 2021
Audit
Dependencies
No dependency data recorded yet.