AWS CDK Library (aws-cdk-lib)

2.244.0 · active · verified Fri Apr 10

AWS Cloud Development Kit v2 — define AWS infrastructure as Python code. Current version: 2.244.0 (Mar 2026). CDK v1 (aws-cdk.core + individual service packages) reached EOL June 2023. v2 consolidates all stable constructs into single 'aws-cdk-lib' package. Import paths completely changed from v1. Construct class moved to separate 'constructs' package. Experimental constructs use '-alpha' suffix packages. Requires CDK CLI ('npm install -g aws-cdk') and 'cdk bootstrap' for each AWS account/region.

Common errors

```
ModuleNotFoundError: No module named 'aws_cdk.core'
```
cause In AWS CDK v2, the 'core' module has been replaced by 'aws-cdk-lib'.

fix Replace 'from aws_cdk import core' with 'from aws_cdk import App, Stack' and import other constructs directly from 'aws_cdk'.
```
ImportError: cannot import name 'core' from 'aws_cdk'
```
cause The 'core' module was removed in AWS CDK v2; all constructs are now imported from 'aws-cdk-lib'.

fix Update imports to 'from aws_cdk import App, Stack' and import other constructs directly from 'aws_cdk'.
```
Cannot find module '@aws-cdk/aws-s3'
```
cause In AWS CDK v2, all service modules are consolidated into 'aws-cdk-lib'.

fix Replace 'import * as s3 from '@aws-cdk/aws-s3'' with 'import * as s3 from 'aws-cdk-lib/aws-s3''.
```
cdk synth: --app is required either in command-line, in cdk.json or in ~/.cdk.json
```
cause The 'cdk synth' command requires the '--app' option to specify the application entry point.

fix Run 'cdk synth --app 'node bin/my-app.js'' or add the 'app' field in 'cdk.json'.
```
cdk deploy: NoSuchBucket error
```
cause The S3 bucket used for deployment does not exist or has been deleted.

fix Ensure the deployment bucket exists or run 'cdk bootstrap' to create the necessary resources.

Warnings

breaking CDK v1 packages (aws-cdk.core, aws-cdk.aws-s3, etc.) are EOL June 2023. All v1 imports broken in v2. LLMs trained pre-2022 generate v1 import patterns.
Fix: Replace all 'from aws_cdk.core import X' with 'from constructs import Construct' and 'from aws_cdk import Stack, App'. Replace 'aws_cdk.aws_s3' with 'aws_cdk.aws_s3' submodule from aws-cdk-lib.
breaking Construct class moved from aws_cdk.core to the separate 'constructs' package. 'from aws_cdk.core import Construct' raises ImportError in v2.
Fix: from constructs import Construct — must install 'constructs' package separately.
breaking CDK v2 requires re-bootstrapping existing AWS accounts. v1 bootstrap resources are incompatible with v2 synthesizer. Error: 'This CDK deployment requires bootstrap stack version X'.
Fix: Run: cdk bootstrap aws://ACCOUNT-ID/REGION for each account/region combination.
breaking cdk synth/deploy requires CDK CLI ('npm install -g aws-cdk'). pip install alone gives you no CLI. Running app.py directly with python produces output but doesn't deploy.
Fix: npm install -g aws-cdk. Then: cdk init, cdk synth, cdk deploy.
gotcha Experimental constructs (alpha packages like aws-cdk.aws-apigatewayv2-alpha) must match aws-cdk-lib version. Mismatched versions cause dependency conflicts.
Fix: Pin alpha packages to same version: pip install 'aws-cdk-lib==2.100.0' 'aws-cdk.aws-apigatewayv2-alpha==2.100.0a0'
gotcha Cloud assembly schema version mismatch error when CDK CLI version is older than aws-cdk-lib version. Error: 'Maximum schema version supported is X.0.0, but found Y.0.0'.
Fix: Update CDK CLI: npm install -g aws-cdk@latest
gotcha lambda_.Runtime.PYTHON_3_8 deprecated. Python 3.8 Lambda runtime EOL Oct 2024. Use PYTHON_3_12 or PYTHON_3_13.
Fix: lambda_.Runtime.PYTHON_3_12 or lambda_.Runtime.PYTHON_3_13
gotcha RemovalPolicy.DESTROY on S3 buckets does not delete bucket contents. Bucket must also have auto_delete_objects=True to actually delete on cdk destroy.
Fix: s3.Bucket(self, 'B', removal_policy=RemovalPolicy.DESTROY, auto_delete_objects=True)
breaking AWS CDK Python applications (aws-cdk-lib) rely on the jsii runtime, which requires Node.js to be installed and available in the system's PATH. A 'FileNotFoundError: No such file or directory: 'node'' occurs if Node.js is missing.
Fix: Install Node.js (e.g., using a package manager like apt, yum, brew, or nvm) and ensure the 'node' executable is accessible in your system's PATH.
breaking The aws-cdk-lib Python package requires the Node.js runtime to be installed and available in the system's PATH due to its reliance on the jsii runtime. Failure to find 'node' will result in a FileNotFoundError during import.
Fix: Install Node.js. For Alpine Linux (python:3.13-alpine), use 'apk add nodejs'.

Install

pip install aws-cdk-lib constructs Python (core — both required)
npm install -g aws-cdk CDK CLI (required separately)

Imports

v2 import pattern

wrong:

# v1 style — all these packages are EOL
from aws_cdk.core import Stack, App, Construct
from aws_cdk import aws_s3 as s3  # wrong in v1 too
import aws_cdk.aws_s3 as s3      # v1 style
from aws_cdk.aws_s3 import Bucket # v1 style

correct:

import aws_cdk as cdk
from aws_cdk import (
    Stack,
    App,
    Duration,
    RemovalPolicy,
    aws_s3 as s3,
    aws_lambda as lambda_,
    aws_iam as iam,
)
from constructs import Construct

class MyStack(Stack):
    def __init__(self, scope: Construct, id: str, **kwargs):
        super().__init__(scope, id, **kwargs)

        bucket = s3.Bucket(
            self, 'MyBucket',
            removal_policy=RemovalPolicy.DESTROY,
            versioned=True
        )

app = App()
MyStack(app, 'MyStack')
app.synth()

v1 used separate packages: aws-cdk.core, aws-cdk.aws-s3, etc. v2 uses single aws-cdk-lib with submodules. Construct class moved from aws_cdk.core to 'constructs' package.

experimental alpha packages

wrong:

# Wrong: trying to import experimental constructs from aws_cdk directly
from aws_cdk import aws_apigatewayv2  # may not exist or be incomplete

correct:

# Stable constructs — from aws_cdk
from aws_cdk import aws_s3 as s3
from aws_cdk import aws_lambda as lambda_

# Experimental constructs — separate alpha package
# pip install aws-cdk.aws-apigatewayv2-alpha
from aws_cdk.aws_apigatewayv2_alpha import HttpApi

# Check stability before using — alpha APIs may break between minor versions

Experimental constructs are in separate '-alpha' packages (e.g. aws-cdk.aws-apigatewayv2-alpha). Alpha APIs can break between minor CDK versions unlike stable aws-cdk-lib.

Quickstart

AWS CDK v2 Python — S3 bucket + Lambda with IAM grant.

# pip install aws-cdk-lib constructs
# npm install -g aws-cdk
# cdk bootstrap aws://ACCOUNT-ID/REGION

import aws_cdk as cdk
from aws_cdk import (
    Stack,
    aws_s3 as s3,
    aws_lambda as lambda_,
    aws_iam as iam,
    Duration,
    RemovalPolicy,
    CfnOutput,
)
from constructs import Construct

class MyAppStack(Stack):
    def __init__(self, scope: Construct, id: str, **kwargs):
        super().__init__(scope, id, **kwargs)

        # S3 bucket
        bucket = s3.Bucket(
            self, 'MyBucket',
            versioned=True,
            removal_policy=RemovalPolicy.DESTROY,
            auto_delete_objects=True
        )

        # Lambda function
        fn = lambda_.Function(
            self, 'MyFunction',
            runtime=lambda_.Runtime.PYTHON_3_12,
            handler='index.handler',
            code=lambda_.Code.from_inline('def handler(e, c): return {"statusCode": 200}'),
            timeout=Duration.seconds(30)
        )

        # Grant bucket read to lambda
        bucket.grant_read(fn)

        # Stack output
        CfnOutput(self, 'BucketName', value=bucket.bucket_name)

app = cdk.App()
MyAppStack(app, 'MyAppStack', env=cdk.Environment(
    account='123456789012',
    region='us-east-1'
))
app.synth()

# Deploy: cdk deploy

view raw JSON →