How to Install AWS CDK: Complete Step-by-Step Guide [2026]

Setting up AWS CDK properly the first time saves hours of debugging later. I've seen too many developers run npm install -g aws-cdk only to hit confusing errors because they missed a prerequisite.

In this guide, you'll learn how to install AWS CDK correctly on macOS, Windows, or Linux. We'll cover every prerequisite, walk through the installation, verify everything works, and troubleshoot common issues.

By the end, you'll have AWS CDK installed, verified, and ready to create your first project. If you're new to the CDK ecosystem, start with what AWS CDK is before diving into installation.

Prerequisites

AWS CDK requires multiple components working together: an AWS account, the AWS CLI, Node.js, and language-specific tools. Missing any of these leads to cryptic errors that waste your time.

Here's the dependency chain you need to complete before installation:

Let me walk you through each requirement.

AWS Account and CLI Setup

Before installing the CDK CLI, you need an AWS account with configured credentials. The CDK CLI uses these credentials when deploying infrastructure to AWS.

What you need:

• An AWS account with an administrative user
• The AWS CLI installed on your local machine
• Credentials configured in your config file

Configuring credentials depends on how your organization manages users:

• IAM Identity Center users (recommended): Run aws configure sso to set up single sign-on
• IAM users: Run aws configure to set access keys directly

The CDK CLI automatically uses your AWS CLI credentials. By default, it uses your default profile, but you can specify a different profile with the --profile option.

For a detailed walkthrough on configuring SSO, check out my guide on how to configure AWS CLI with SSO.

Node.js Installation

Here's something that catches many developers off guard: Node.js is required regardless of which programming language you use with CDK. Whether you're writing CDK apps in Python, Java, or Go, the CDK CLI runs on a Node.js backend.

Current requirement: Node.js 22.x or later

I recommend using an active LTS (Long Term Support) version for stability. Here's the current support timeline:

AWS CDK continues supporting Node.js versions for 6 months past their official End-of-Life dates, giving you time to upgrade. That said, staying on supported versions ensures you receive security updates and access to the latest CDK features.

Language-Specific Requirements

If you're using TypeScript or JavaScript, you're already set after installing Node.js. For other languages, install these additional prerequisites:

TypeScript:

npm -g install typescript

Requires TypeScript 3.8 or later.

JavaScript: No additional requirements beyond Node.js.

Python:

• Python 3.7 or later
• Must include pip and virtualenv

Java:

• JDK 8 (1.8) or later
• Apache Maven 3.5 or later
• Set the JAVA_HOME environment variable to your JDK installation path

C#:

• .NET Core 3.1 or later, or .NET 6.0 or later

Go:

• Go 1.18 or later

With prerequisites in place, you're ready to install the CDK CLI.

Install AWS CDK

Installing AWS CDK takes a single command. AWS recommends installing it globally so you can use the cdk command from any directory.

Global Installation (Recommended)

Run this command in your terminal:

npm install -g aws-cdk

That's it. The -g flag installs the package globally, making the cdk command available system-wide.

Install a Specific Version

For team standardization or compatibility requirements, you can install a specific CDK version:

npm install -g aws-cdk@2.170.0

Replace 2.170.0 with your target version. This is useful when your team needs everyone on the same CDK version, or when a project requires compatibility with a specific release.

Local Project Installation

If you work with multiple CDK projects requiring different versions, consider local installation:

npm install aws-cdk

Without the -g flag, npm installs the CDK CLI locally in your project's node_modules folder. Invoke it using npx:

npx cdk deploy

The npx command runs the local version if it exists, falling back to a globally installed version if not. This approach gives you version isolation between projects.

Verify Your Installation

After installation, verify that everything works correctly. Run:

cdk --version

You should see output showing the version number:

2.1026.0 (build ad1a7ce)

This confirms three things:

1. The CDK CLI installed successfully
2. The CLI is accessible from your command line
3. The installation is functioning correctly

You can also run cdk --help to see all available commands, but the version check is sufficient for verification.

Troubleshooting Common Issues

If installation doesn't go smoothly, here are the most common issues and their solutions.

Permission errors on macOS/Linux:

If you see permission denied errors, run the install with sudo:

sudo npm install -g aws-cdk

This grants npm the permissions needed to install globally. On macOS, you might also consider fixing npm's default directory permissions to avoid needing sudo in the future.

Installation failures:

If the installation fails with an error message, try a clean reinstall:

npm uninstall -g aws-cdk
npm install -g aws-cdk

"cdk command not found":

This usually means npm's global bin directory isn't in your PATH. First, find where npm installs global packages:

npm config get prefix

Then add the resulting path's bin subdirectory to your system's PATH environment variable.

Node.js version conflicts:

If you're managing multiple Node.js versions across projects, use nvm (Node Version Manager) to switch between versions easily. This is particularly helpful when different projects require different Node.js versions.

Next Steps After Installation

With CDK installed and verified, you have two important next steps before you can deploy infrastructure.

Bootstrap Your AWS Environment

Before deploying any CDK application, you must bootstrap each AWS environment (account/region combination) you plan to use. Bootstrapping creates the resources CDK needs for deployments:

• An S3 bucket for storing deployment assets (CloudFormation templates, Lambda code)
• IAM roles with permissions for CDK deployments
• A CloudFormation stack called CDKToolkit that manages these resources

From within a CDK project directory, run:

cdk bootstrap

Or specify the environment explicitly:

cdk bootstrap aws://123456789012/us-east-1

You can bootstrap multiple environments at once:

cdk bootstrap aws://123456789012/us-east-1 aws://123456789012/eu-west-1

It's safe to run bootstrap multiple times. If the environment is already bootstrapped, the command either upgrades the stack if needed or does nothing.

If you skip bootstrapping and try to deploy, you'll see this error:

Deployment failed: Error: SSM parameter /cdk-bootstrap/hnb659fds/version not found.
Has the environment been bootstrapped? Please run 'cdk bootstrap'

For a deeper dive into bootstrapping options and customization, see my guide on bootstrapping your AWS environment.

Create Your First CDK Project

With bootstrapping complete, create your first project using cdk init:

mkdir my-cdk-project && cd my-cdk-project
cdk init app --language typescript

The command creates a complete project structure with:

• Configuration files (cdk.json, package.json, tsconfig.json)
• A sample CDK stack in the lib directory
• A Git repository initialization

For production applications, you'll want to evolve this initial structure. See our complete guide to CDK project structure to understand how to organize stacks, constructs, tests, and assets as your application grows.

Supported languages include: typescript, javascript, python, java, csharp, and go.

For Python projects, activate the virtual environment and install dependencies after initialization:

source .venv/bin/activate  # On Windows: .venv\Scripts\activate
python -m pip install -r requirements.txt

For Java projects, install dependencies with:

mvn package

Skip the Boilerplate with a Starter Kit

If you want to skip the manual setup and start with production-ready defaults, try the AWS CDK Starter Kit. It's a TypeScript template with secure OIDC authentication, automated CI/CD, and branch-based deployments baked in.

I built this after copy-pasting the same boilerplate across multiple projects. It includes an optimized project structure and a secure GitHub Actions pipeline using OIDC for temporary credentials instead of long-lived access keys. See the AWS CDK Starter Kit documentation for setup instructions.

For a complete walkthrough of CDK development, check out my AWS CDK guide which covers constructs, stacks, and deployment workflows.

Update AWS CDK

Keeping your CDK installation current ensures you have the latest features, bug fixes, and security patches.

Update to the latest version:

npm update -g aws-cdk

After updating, verify the new version:

cdk --version

Using Yarn? If you installed CDK with Yarn, update with:

yarn global upgrade aws-cdk

For release notes and changelogs, check the AWS CDK releases page on GitHub.