Install & Compatibility
Where this runs
tested against v2.259.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.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 24.6MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.7s · import 0.000s · 25MB
23MB installed
● package 23MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
CloudAssembly
✓ from aws_cdk.cx_api import CloudAssembly
✗ from @aws-cdk/cloud-assembly-schema import CloudAssembly
In CDK v2, all core constructs are under `aws_cdk` namespace. `CloudAssembly` is the primary class for loading synthesized assemblies. The `wrong` example shows a common mistake from CDK v1 (JavaScript) or attempting to import schema directly.
CloudAssemblyBuilder
✓ from aws_cdk.cx_api import CloudAssemblyBuilder
Used to programmatically create or build a Cloud Assembly structure.
ArtifactType
✓ from aws_cdk.cx_api import ArtifactType
Enum representing different types of artifacts within a Cloud Assembly (e.g., CloudFormation stack, asset).
This quickstart demonstrates how to load and inspect a synthesized AWS CDK Cloud Assembly. It assumes a `cdk.out` directory has been created by running `cdk synth` in a CDK project. It then prints details about the assembly, including its stacks and artifacts. An alternative path is provided to create an empty assembly programmatically if no `cdk.out` is available.
import os
from aws_cdk.cx_api import CloudAssembly, CloudAssemblyBuilder
# Assuming 'cdk.out' exists in the current directory, typically created by 'cdk synth'.
assembly_path = "./cdk.out"
if os.path.isdir(assembly_path):
print(f"Loading Cloud Assembly from: {assembly_path}")
try:
assembly = CloudAssembly(directory=assembly_path)
print(f"Assembly ID: {assembly.id}")
print(f"Version: {assembly.version}")
print("Found stacks:")
for stack in assembly.stacks:
print(f"- {stack.stack_name} (Env: {stack.environment.name})")
print("Artifacts:")
for artifact in assembly.artifacts:
print(f"- {artifact.id} (Type: {type(artifact).__name__})")
except Exception as e:
print(f"Error loading Cloud Assembly: {e}")
print("Ensure 'cdk synth' was run successfully and 'cdk.out' is valid.")
else:
print(f"Directory '{assembly_path}' not found. Please run 'cdk synth' in a CDK project first.")
print("Alternatively, you can create an empty assembly programmatically:")
builder = CloudAssemblyBuilder(outdir="temp_cdk_out")
builder.build()
print("Created empty assembly in 'temp_cdk_out'.")
# os.system("rm -rf temp_cdk_out") # Uncomment to clean up automatically
Debug
Known issues
breakingMigration from AWS CDK v1 to v2 consolidated all modules under the `aws_cdk` namespace. This means import paths for `aws-cdk-cx-api` classes changed significantly.fixUpdate all imports from `aws_cdk.cx_api.ClassName` (or similar v1 patterns like `@aws-cdk/cloud-assembly-schema` in JavaScript) to `from aws_cdk.cx_api import ClassName` for v2.
affects: CDK v1.x to v2.x
gotchaThe `aws-cdk-cx-api` library is for *inspecting* Cloud Assemblies, not for *defining* CDK applications. It operates on the output of `cdk synth` (the `cdk.out` directory).fixUse `aws-cdk-lib` for defining CDK constructs, stacks, and apps. Use `aws-cdk-cx-api` when you need to programmatically analyze or manipulate the synthesized `cdk.out` output.
affects: All v2.x versions
gotchaThe schema of the Cloud Assembly (`manifest.json`, `tree.json`, etc.) can evolve between minor versions of CDK. Loading an assembly synthesized with a much older or newer CDK CLI version might lead to parsing errors.fixEnsure your `aws-cdk-cx-api` library version and the CDK CLI version used to synthesize the `cdk.out` directory are reasonably compatible. Upgrade both if encountering unexpected parsing failures.
affects: All v2.x versions (minor versions)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'aws_cdk.cx_api'
The `aws-cdk-cx-api` package is not installed, or you are trying to use a CDK v1 import style for v2.
fixRun `pip install aws-cdk-cx-api`. If migrating from v1, ensure all imports use the `from aws_cdk.cx_api import ...` pattern.
jsii.errors.JavaScriptError: CloudAssembly directory does not exist: '<path_to_cdk.out>'
The specified directory for `CloudAssembly` (typically `cdk.out`) does not exist or the path is incorrect.
fixVerify that `cdk synth` has been run successfully in your CDK project, creating the `cdk.out` directory. Check the path passed to `CloudAssembly(directory=...)`.
jsii.errors.JavaScriptError: Manifest file 'manifest.json' not found in '<path_to_cdk.out>'
The `cdk.out` directory exists, but it's either empty, corrupted, or does not contain a valid `manifest.json` file, which is crucial for defining the Cloud Assembly.
fixRe-run `cdk synth` to ensure a complete and valid `cdk.out` directory is generated. Check the CDK CLI output for any errors during synthesis.
Upgrade
Version history
2.259.0latest on PyPI · released Jun 12, 2026
Audit
Dependencies
pythonrequiredRuntime compatibility