Install & Compatibility
Where this runs
tested against v1.204.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 · 28.4MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 3.4s · import 0.000s · 29MB
27MB installed
● package 27MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
App
✓ from aws_cdk import core
Stack
✓ from aws_cdk import core
Bucket
✓ from aws_cdk.aws_s3 import Bucket
✗ from aws_cdk_lib.aws_s3 import Bucket
The `aws-cdk-lib` package and its submodules are for AWS CDK v2. In CDK v1, service constructs were imported from separate `aws_cdk.aws_*` packages.
This quickstart demonstrates how to create a basic AWS CDK v1 application in Python, define an S3 bucket, and synthesize it into a CloudFormation template. It assumes the AWS CDK CLI (Node.js based) is already installed globally. Replace `CDK_DEFAULT_ACCOUNT` and `CDK_DEFAULT_REGION` with your AWS account ID and desired region, respectively. The `cdk bootstrap` command is typically a one-time setup per AWS account and region to provision resources required by the CDK.
# 1. Initialize a new CDK project (requires Node.js and 'aws-cdk' CLI installed)
# mkdir my-cdk-app
# cd my-cdk-app
# cdk init app --language python
# 2. Install dependencies
# pip install -r requirements.txt
# 3. Define a simple stack (in my_cdk_app/my_cdk_app_stack.py)
from aws_cdk import core as cdk
from aws_cdk import aws_s3 as s3
class MyCdkAppStack(cdk.Stack):
def __init__(self, scope: cdk.Construct, construct_id: str, **kwargs) -> None:
super().__init__(scope, construct_id, **kwargs)
s3.Bucket(self, "MyFirstBucket",
versioned=True,
bucket_name=f"my-first-cdk-bucket-{cdk.Aws.ACCOUNT_ID}")
# 4. Instantiate the app and stack (in app.py)
import os
app = cdk.App()
MyCdkAppStack(app, "MyCdkAppStack",
env=cdk.Environment(
account=os.environ.get('CDK_DEFAULT_ACCOUNT', ''),
region=os.environ.get('CDK_DEFAULT_REGION', 'us-east-1'))
)
app.synth() # Generates CloudFormation template
# 5. Deploy (from terminal)
# cdk bootstrap # First-time setup per AWS account/region
# cdk deploy MyCdkAppStack
cdk --version
Debug
Known issues
breakingAWS CDK v1, including `aws-cdk-core`, reached its official end-of-support on June 1, 2023. This means it no longer receives maintenance, updates, security patches, or technical support. Continued use can expose applications to security vulnerabilities and unaddressed bugs.fixMigrate your applications to AWS CDK v2 as soon as possible. AWS provides a detailed migration guide.
affects: All 1.x versions
breakingMigrating from AWS CDK v1 (`aws-cdk-core`) to v2 (`aws-cdk-lib`) involves significant breaking changes. These include a consolidated single package (`aws-cdk-lib`) for stable constructs, changes in import statements, and a requirement to re-bootstrap AWS accounts with the modern bootstrap stack.fixUpdate `requirements.txt` to `aws-cdk-lib` and `constructs`. Adjust import statements (e.g., `from aws_cdk import App, Stack` instead of `from aws_cdk import core`). Run `cdk bootstrap` with a v2-compatible CLI. Review the official AWS CDK v2 migration guide.
affects: All 1.x to 2.x migration
gotchaThe Python version specified in `pyproject.toml` or `requirements.txt` (`~=3.7` for `aws-cdk-core`) for the CDK library itself might be different from the Python version required by the global AWS CDK CLI for optimal compatibility or newer features. For AWS CDK v2, Python 3.9 or later is required.fixAlways use a supported Python version. For CDK v2, ensure Python 3.9+ is installed. It is also critical to ensure the global `aws-cdk` CLI version is compatible with your project's CDK library version, ideally keeping them in sync.
affects: All 1.x versions, especially when using a newer CLI
gotchaDue to Python's dynamic typing, it's easy to pass an incorrect type of value to an AWS CDK construct, which can lead to runtime errors when the JSII layer (which translates between Python and the CDK's TypeScript core) fails.fixLeverage IDEs with good type validation support and consult CDK API documentation for expected parameter types. Implement unit tests for your constructs.
affects: All 1.x versions
gotchaComplex CDK applications can quickly hit AWS CloudFormation resource limits (e.g., maximum number of resources in a stack), leading to synthesis errors.fixModularize your infrastructure into smaller, interconnected stacks. Use higher-level constructs (L2/L3 patterns) which abstract multiple underlying CloudFormation resources.
affects: All 1.x versions
Errors
Common errors & fixes
Deployment failure due to missing permissions
The IAM role used by the CDK deployment or the CloudFormation execution role lacks necessary permissions for the resources being deployed.
fixEnsure the IAM role performing the `cdk deploy` command has sufficient permissions. Check the CloudFormation Events tab in the AWS Console for specific permission errors. Follow the principle of least privilege.
Context value not found for lookup (e.g., VPC, availability zones)
CDK cannot retrieve specific environment information (e.g., existing VPC IDs) which are often fetched from your AWS account during `cdk synth`.
fixRun `cdk context --reset` or `cdk synth` / `cdk deploy` again to refresh the context values in `cdk.context.json`. Ensure your AWS CLI is configured with correct credentials and region.
Cyclic dependencies are not allowed
Your CDK stacks have circular dependencies, meaning Stack A depends on Stack B, and Stack B simultaneously depends on Stack A.
fixRestructure your stacks to break circular dependencies. Use `cdk.Fn.importValue` or AWS SSM Parameter Store for cross-stack references where direct dependencies are problematic.
--app is required either in command-line in cdk.json or in ~/.cdk.json
The CDK CLI cannot locate your application's entry point, typically `app.py` for Python projects.
fixEnsure you are running `cdk` commands from the root directory of your CDK project, or explicitly specify the app entry point using `cdk synth --app 'python app.py'` (or similar for other languages).
Upgrade
Version history
1.204.0latest on PyPI · released Jun 19, 2023
Audit
Dependencies
Node.jsrequiredThe AWS CDK Toolkit (CLI) is built on Node.js and is essential for synthesizing and deploying CDK applications.