Install & Compatibility
Where this runs
tested against v0.21.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.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 398.5MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 13.4s · import 0.000s · 399MB
470MB installed
● package 470MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
App
✓ from cdktf import App
Represents the CDKTF application.
TerraformStack
✓ from cdktf import TerraformStack
The base class for defining a stack of Terraform resources.
Construct
✓ from constructs import Construct
Base class for all constructs, shared with AWS CDK.
AwsProvider
✓ from cdktf_cdktf_provider_aws.provider import AwsProvider
Provider import for AWS. Provider imports generally follow 'cdktf_cdktf_provider_<provider_name>.provider'.
This quickstart defines an AWS S3 bucket. First, initialize a new CDKTF project with `cdktf init --template=python --providers=aws` in an empty directory. Then, replace the content of `main.py` with the code above. Ensure AWS credentials and default region are configured (e.g., via environment variables `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`). Run `cdktf get` to generate provider bindings, then `cdktf deploy` to provision the bucket.
import os
from constructs import Construct
from cdktf import App, TerraformStack, TerraformOutput
from cdktf_cdktf_provider_aws.provider import AwsProvider
from cdktf_cdktf_provider_aws.s3 import S3Bucket
class MyStack(TerraformStack):
def __init__(self, scope: Construct, id: str):
super().__init__(scope, id)
AwsProvider(self, 'Aws', region=os.environ.get('AWS_REGION', 'us-east-1'))
bucket = S3Bucket(self, 'MyBucket',
bucket_prefix="my-unique-cdktf-bucket-",
tags={
"Environment": "Development",
"ManagedBy": "CDKTF"
}
)
TerraformOutput(self, 'bucket_name', value=bucket.id)
app = App()
MyStack(app, 'my-cdktf-aws-stack')
app.synth()
cdktf --version
Debug
Known issues
breakingCDKTF is officially deprecated as of December 10, 2025. HashiCorp will no longer maintain or develop the project, and no further updates, fixes, or compatibility changes will be provided.fixHashiCorp recommends migrating to standard Terraform HCL or AWS CDK if your infrastructure is tightly integrated with AWS CDK. Community forks may emerge, but continued use of CDKTF will be at your own risk.
affects: All versions, effective from 0.21.0 onwards.
breakingPrior to reaching version 1.0, CDKTF followed semantic versioning where even minor version bumps could introduce breaking changes to APIs, generated provider bindings, and the synthesis process.fixAlways consult the GitHub CHANGELOG and upgrade guides (available on the HashiCorp Developer site) for each specific version you are upgrading to. It's recommended to upgrade frequently in small steps.
affects: < 1.0.0
gotchaProvider import paths changed significantly in version 0.13. Previously, providers might be imported directly from `cdktf_cdktf_provider_<provider_name>`. The correct pattern now is typically `from cdktf_cdktf_provider_<provider_name>.provider import <ProviderName>`.fixUpdate provider import statements to reflect the nested `provider` module. For example, `from cdktf_cdktf_provider_aws.provider import AwsProvider`.
affects: < 0.13.0
gotchaMismatched versions between the `cdktf-cli` and the `cdktf` Python library can lead to subtle and confusing errors during synthesis or deployment.fixEnsure that your globally installed `cdktf-cli` (`npm install --global cdktf-cli@latest`) and the `cdktf` Python library (`pip install cdktf`) are kept in sync, ideally running the same version number.
affects: All versions
gotchaAfter adding or modifying Terraform providers/modules in `cdktf.json` or installing new provider Python packages, you must run `cdktf get`. This command generates the necessary CDK Constructs for Terraform providers and modules within your project.fixAlways run `cdktf get` after changing provider configurations or installing new provider bindings to ensure your project has the latest generated classes.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'cdktf' OR ImportError: cannot import name 'AwsProvider' from 'imports.aws'
The required CDKTF Python package or its generated provider bindings are not installed in the active Python environment, or 'cdktf get' was not run after adding a provider, or the import path is outdated for newer CDKTF versions.
fixRun 'pipenv install cdktf' or 'pip install cdktf'. For provider imports, ensure the provider is added with 'cdktf provider add <provider@version>' and then run 'cdktf get'. For CDKTF versions 0.13+, import providers from 'cdktf_cdktf_provider_<provider_name>' (e.g., 'from cdktf_cdktf_provider_aws import AwsProvider') instead of 'imports.<provider_name>'.
TypeError: 'module' object is not callable
This error occurs when attempting to call a Python module as if it were a constructor, instead of a specific class within that module.
fixEnsure you are importing and instantiating the correct class from the provider module. For example, if importing 'from cdktf_cdktf_provider_aws import ec2', you should instantiate a resource like 'ec2.Instance()' and not 'ec2()' or 'AwsProvider()' if 'AwsProvider' is not the top-level class to be called directly from that import.
FileNotFoundError: [Errno 2] No such file or directory: 'node'
CDKTF relies on Node.js and its 'jsii' component to synthesize infrastructure code into Terraform's JSON configuration, and this error indicates that Node.js is not installed or not found in the system's PATH.
fixInstall Node.js (and npm) on your operating system and ensure it is included in your system's PATH. For Linux, this often involves 'sudo apt install nodejs npm' or using a version manager like 'nvm'.
AttributeError: module 'cdktf' has no attribute 'ITerraformDependable'
This usually signals a version incompatibility between your 'cdktf-cli' and the 'cdktf' Python library in your project, or a breaking change in the CDKTF API that your code is not aligned with.
fixKeep your 'cdktf-cli' and 'cdktf' library versions in sync. Upgrade both the CLI ('npm install -g cdktf-cli@latest') and update your project's 'requirements.txt' or 'Pipfile' to use the latest compatible 'cdktf' version, then run 'pip install -r requirements.txt' or 'pipenv install'. Upgrade
Version history
0.21.0latest on PyPI · released Jun 4, 2025
Audit
Dependencies
pythonrequiredRequired for running the Python application.
Node.jsrequiredRequired for the `cdktf-cli`.
npmrequiredPackage manager for `cdktf-cli`.
Terraform CLIrequiredCDKTF synthesizes to Terraform HCL, requiring the Terraform CLI for plan/apply operations.