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.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 60.1MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 7.6s · import 0.000s · 61MB
63MB installed
● package 63MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Project
✓ from aws_cdk import aws_codebuild as codebuild
✗ from aws_cdk_lib import aws_codebuild as codebuild
This import path is specific to AWS CDK v1. AWS CDK v2 consolidates all constructs under `aws_cdk_lib`.
Source
✓ from aws_cdk import aws_codebuild as codebuild
✗ from aws_cdk_lib import aws_codebuild
When using `aws-cdk.aws-codebuild` (v1), ensure your imports correctly reference `aws_cdk.aws_codebuild`.
BuildSpec
✓ from aws_cdk import aws_codebuild as codebuild
✗ import aws_cdk.aws_codebuild
While direct import works, aliasing `aws_codebuild` as `codebuild` is a common convention for brevity and readability.
This quickstart demonstrates how to define a basic AWS CodeBuild project using AWS CDK v1. It creates a project with an inline build specification that prints a message during the build phase and uses `Source.no_source()` for simplicity. For deployment, ensure your AWS environment is configured (e.g., `aws configure`) and you have bootstrapped your CDK environment (`cdk bootstrap`). You can then run `cdk synth` to generate CloudFormation or `cdk deploy` to deploy it.
import os
from aws_cdk import ( # type: ignore
core as cdk,
aws_codebuild as codebuild
)
class MyCodeBuildStack(cdk.Stack):
def __init__(self, scope: cdk.App, construct_id: str, **kwargs) -> None:
super().__init__(scope, construct_id, **kwargs)
# Define a simple CodeBuild project that prints a message
codebuild.Project(
self,
"MySimpleBuildProject",
project_name="MySimpleBuildProject",
build_spec=codebuild.BuildSpec.from_object({
"version": "0.2",
"phases": {
"install": {
"commands": [
"echo 'Installing dependencies...'"
]
},
"build": {
"commands": [
"echo 'Hello from CodeBuild!'",
"env"
]
}
},
"artifacts": {
"files": []
}
}),
source=codebuild.Source.no_source(), # No external source needed for this basic example
environment=codebuild.BuildEnvironment(
build_image=codebuild.LinuxBuildImage.STANDARD_5_0
)
)
app = cdk.App()
MyCodeBuildStack(app, "CodeBuildQuickstartStack")
app.synth()
Debug
Known issues
breakingAWS CDK v1 (`aws-cdk.*` packages) and v2 (`aws-cdk-lib`) have fundamentally different import paths and API structures. Using v1 packages with v2 imports, or vice-versa, will lead to `ModuleNotFoundError` or `AttributeError`.fixFor new projects, strongly consider using AWS CDK v2 (`pip install aws-cdk-lib`). For existing v1 projects, ensure `aws-cdk.core` and specific `aws-cdk.aws-*` packages are installed and use v1 import patterns. Refer to the official AWS CDK v2 upgrade guide for migration details.
affects: All versions of aws-cdk-aws-codebuild (v1) when mixing with aws-cdk-lib (v2).
gotchaCodeBuild projects require an IAM service role with explicit permissions to access any AWS resources they interact with (e.g., S3 buckets for artifacts, ECR repositories for images, KMS keys, etc.). Missing permissions are a frequent cause of build failures.fixReview the CodeBuild logs carefully for access denied messages. Grant necessary IAM permissions to the `project.role` using methods like `project.role.add_to_policy()`, or define a custom `iam.Role` and assign it to the project. Always use `cdk diff` to inspect IAM policy changes before deploying.
affects: All versions.
gotchaThe `BuildSpec` configuration is sensitive to syntax and content. Incorrect YAML, invalid phase names, or commands referencing non-existent paths/executables will cause the build to fail.fixValidate your `BuildSpec` YAML syntax. Consult the official AWS CodeBuild User Guide for the correct `BuildSpec` schema and examples. Test complex `BuildSpec` files in a controlled environment or iterate quickly with small changes.
affects: All versions.
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'aws_cdk.aws_codebuild'
The `aws-cdk.aws-codebuild` package (for CDK v1) is not installed, or you might be trying to use v1 imports while having only `aws-cdk-lib` (CDK v2) installed.
fixIf using CDK v1, run `pip install aws-cdk.aws-codebuild`. If intending to use CDK v2, install `aws-cdk-lib` and update your imports to `from aws_cdk_lib import aws_codebuild`.
AttributeError: module 'aws_cdk' has no attribute 'aws_codebuild'
This error occurs when `aws-cdk-lib` (CDK v2) is installed, but the code attempts to use a v1 import path like `from aws_cdk import aws_codebuild`. In v2, all constructs are consolidated under `aws_cdk_lib`.
fixIf you are using CDK v2, change your import statement to `from aws_cdk_lib import aws_codebuild as codebuild`. If you intend to use v1, ensure only v1 packages are installed (`aws-cdk.core`, `aws-cdk.aws-codebuild`) and no v2 packages like `aws-cdk-lib`.
CodeBuild project failed with exit code 1
A generic build failure. Common culprits are misconfigured `BuildSpec`, insufficient IAM permissions for the CodeBuild service role, or issues with the source code or build environment.
fixInspect the detailed build logs in the AWS CodeBuild console for specific error messages. These logs will usually pinpoint the exact line in your `BuildSpec` that failed, or indicate a permissions issue (`AccessDenied`). Address the root cause based on log output.
Upgrade
Version history
1.204.0latest on PyPI · released Jun 19, 2023
Audit
Dependencies
aws-cdk.corerequiredProvides core CDK constructs, app, and stack definitions, essential for any CDK application.
aws-cdk.aws-s3optionalFrequently used with CodeBuild for source artifacts, build outputs, or caching.