AWS CDK Library (aws-cdk-lib)

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)

Install

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

Imports

• v2 import pattern

  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

  # 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