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.940 runs
installs and imports cleanly · install 0.0s · import 0.000s · 480MB
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 11.3s · import 0.000s · 551MB
555MB installed
● package 555MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
aws_ec2
✓ from aws_cdk import aws_ec2 as ec2
Vpc
✓ from aws_cdk.aws_ec2 import Vpc
✗ from aws_cdk_lib.aws_ec2 import Vpc
This is a v1 import path; v2 uses 'aws_cdk.aws_ec2' directly within 'aws-cdk-lib'.
This quickstart code defines an AWS CDK v1 stack in Python that provisions a new VPC with public and private subnets, and an EC2 T3.Micro instance running Amazon Linux 2 within that VPC. It then outputs the public IP address of the instance. Replace 'MyKeyPair' with an existing EC2 Key Pair in your AWS account. You'll need to run `cdk bootstrap` and configure `CDK_DEFAULT_ACCOUNT` and `CDK_DEFAULT_REGION` environment variables before deploying with `cdk deploy`.
import os
from aws_cdk import (
core,
aws_ec2 as ec2
)
class Ec2Stack(core.Stack):
def __init__(self, scope: core.Construct, id: str, **kwargs) -> None:
super().__init__(scope, id, **kwargs)
# Create a VPC
vpc = ec2.Vpc(self, "MyVpc",
cidr="10.0.0.0/16",
max_azs=2,
subnet_configuration=[
ec2.SubnetConfiguration(
name="Public",
subnet_type=ec2.SubnetType.PUBLIC,
cidr_mask=24
),
ec2.SubnetConfiguration(
name="Private",
subnet_type=ec2.SubnetType.PRIVATE_WITH_EGRESS,
cidr_mask=24
)
]
)
# Define an Amazon Linux 2 AMI
ami = ec2.MachineImage.latest_amazon_linux(
generation=ec2.AmazonLinuxGeneration.AMAZON_LINUX_2,
edition=ec2.AmazonLinuxEdition.STANDARD,
virtualization=ec2.AmazonLinuxVirt.HVM,
storage=ec2.AmazonLinuxStorage.GENERAL_PURPOSE
)
# Create an EC2 instance
instance = ec2.Instance(self, "MyInstance",
vpc=vpc,
instance_type=ec2.InstanceType.of(
ec2.InstanceClass.T3,
ec2.InstanceSize.MICRO
),
machine_image=ami,
key_name="MyKeyPair" # Ensure this key pair exists in your AWS account
)
# Output the public IP address of the EC2 instance
core.CfnOutput(self, "InstancePublicIp", value=instance.instance_public_ip)
app = core.App()
Ec2Stack(app, "MyEc2Stack",
env=core.Environment(
account=os.environ.get("CDK_DEFAULT_ACCOUNT"),
region=os.environ.get("CDK_DEFAULT_REGION")
)
)
app.synth()
Debug
Known issues
breakingAWS CDK v1 construct libraries like `aws-cdk.aws-ec2` are separate packages. AWS CDK v2 consolidates all stable constructs into a single package, `aws-cdk-lib`. Migrating from v1 to v2 requires updating import statements (e.g., `from aws_cdk import aws_ec2` becomes `from aws_cdk.aws_ec2`), re-bootstrapping environments, and may involve API changes.fixRefer to the official AWS CDK Migration Guide for v1 to v2. For new projects, it is highly recommended to use `aws-cdk-lib` (CDK v2).
affects: All versions of aws-cdk.aws-ec2 (v1) when migrating to CDK v2
deprecatedAWS CDK v1 reached End-of-Support on June 1, 2023. While packages like `aws-cdk.aws-ec2` are still available on PyPI, they are no longer actively updated and users are encouraged to migrate to AWS CDK v2 for continued support and new features.fixPlan to migrate your CDK applications to AWS CDK v2. Install `aws-cdk-lib` and update your code accordingly.
affects: 1.x.x
gotchaBy default, a `Vpc` construct will create NAT Gateways in every public subnet, which incur costs.fixTo control NAT Gateway creation, specify `nat_gateways: 0` in your `Vpc` props and configure alternative egress paths, or use `ec2.SubnetType.PRIVATE_ISOLATED` for subnets that do not require internet access.
affects: All versions
gotchaThe `Vpc` construct, when looking up an existing VPC using `Vpc.from_lookup()`, writes context values to `cdk.context.json`. This file must be committed to source control to ensure repeatable builds and functionality in CI/CD environments.fixEnsure `cdk.context.json` is committed to your repository and not ignored by `.gitignore`.
affects: All versions
gotchaUsing `MachineImage.latest_amazon_linux()` or similar methods might result in different AMIs over time. If precise AMI control is needed for consistency or compliance, use a specific AMI ID or an SSM parameter. The AWS official NAT instance AMI reached EOL on Dec 31, 2023.fixFor production environments requiring specific AMI versions, use `MachineImage.generic_linux(ami_map={'region': 'ami-id'})` or `MachineImage.from_ssm_parameter('parameter-name')`. affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'aws_cdk.aws_ec2'
The Python package `aws-cdk.aws-ec2` is not installed in your environment or you are attempting to use v1 import syntax with a v2 `aws-cdk-lib` installation without proper aliasing.
fixFor AWS CDK v1, run `pip install aws-cdk.aws-ec2`. For AWS CDK v2, ensure `pip install aws-cdk-lib` is run and update your imports to `from aws_cdk import aws_ec2 as ec2` if still using the v1-style import, or directly `from aws_cdk.aws_ec2 import Vpc` etc. if using v2's consolidated library.
Error: Stack 'MyStack' requires account number and region. Please specify them using the 'env' property when defining the stack, or using the CDK_DEFAULT_ACCOUNT and CDK_DEFAULT_REGION environment variables.
CDK applications need to know the target AWS account and region for deployment. This information was not provided in the stack definition or via environment variables.
fixDefine `env` in your stack: `env=core.Environment(account='YOUR_ACCOUNT_ID', region='YOUR_REGION')` or set environment variables: `export CDK_DEFAULT_ACCOUNT='YOUR_ACCOUNT_ID'` and `export CDK_DEFAULT_REGION='YOUR_REGION'`.
cdk deploy failed. Stack 'MyEc2Stack' is in ROLLBACK_COMPLETE state.
A previous deployment attempt failed and rolled back, leaving the CloudFormation stack in a non-deployable state for direct updates. This can be due to various configuration errors or resource limits.
fixInspect the CloudFormation events in the AWS console for detailed error messages. Often, deleting the stack (`cdk destroy MyEc2Stack`) and redeploying after fixing the issue is the quickest way to resolve this, especially during initial development.
jsii.errors.JSIIError: Could not find any AMIs for the given criteria
The `MachineImage` parameters (e.g., `AmazonLinuxGeneration`, `edition`, `virtualization`, `storage`) did not match any available AMIs in the specified AWS region, or the region does not support the requested configuration.
fixDouble-check the `MachineImage` criteria against the AWS console or documentation for the target region. Consider using a specific AMI ID if you know it, or broaden your search criteria. Ensure your `CDK_DEFAULT_REGION` is correctly set.
Upgrade
Version history
1.204.0latest on PyPI · released Jun 19, 2023
Audit
Dependencies
aws-cdkrequiredCore AWS CDK framework for v1 constructs.
constructsrequiredFoundational building blocks for CDK applications.