Install & Compatibility
Where this runs
tested against v0.0.18 · 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 · 88MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 6.5s · import 0.000s · 74MB
80MB installed
● package 80MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Image
✓ from pulumi_dockerbuild import Image
Index
✓ from pulumi_dockerbuild import Index
ImageRegistryArgs
✓ from pulumi_dockerbuild import ImageRegistryArgs
This quickstart demonstrates how to build a Docker image using `pulumi-docker-build`. It creates a simple `Dockerfile` in the current directory, then defines an `Image` resource to build and optionally push the image to Docker Hub. Remember to replace 'yourusername' with your actual Docker Hub username and set `DOCKER_USERNAME` and `DOCKER_PASSWORD` environment variables for pushing.
import pulumi
import pulumi_dockerbuild as dockerbuild
import os
# For this quickstart, we'll create a simple Dockerfile temporarily.
# In a real project, this Dockerfile would be part of your source code.
with open("Dockerfile", "w") as f:
f.write("""
FROM alpine:latest
RUN echo "Building with Pulumi Docker Build!" > /tmp/build-status.txt
CMD ["cat", "/tmp/build-status.txt"]
""")
# Define a Docker image resource. This will build the image.
# To push to Docker Hub, replace 'yourusername' with your Docker Hub username
# and ensure DOCKER_USERNAME and DOCKER_PASSWORD environment variables are set.
# For local builds only, you can omit the 'registry' argument.
image = dockerbuild.Image("my-first-image",
context=".",
dockerfile="Dockerfile",
image_name=f"yourusername/my-first-image:v1.0.0", # IMPORTANT: Replace 'yourusername'
registry=dockerbuild.ImageRegistryArgs(
server="docker.io", # Default for Docker Hub
username=os.environ.get("DOCKER_USERNAME", ""),
password=os.environ.get("DOCKER_PASSWORD", ""),
),
# If you want to export the image to a local tarball instead of pushing:
# exports=[dockerbuild.ImageExportArgs(
# local=dockerbuild.ImageExportLocalArgs(
# dest="./my-first-image.tar"
# )
# )]
)
# Export the resulting image name
pulumi.export("image_name", image.image_name)
# Note: Remember to delete the 'Dockerfile' created by this quickstart
# after you are done, as it's a temporary artifact for demonstration.
pulumi --version
Debug
Known issues
breakingUpgrades to underlying `buildx` and BuildKit versions (e.g., in v0.0.8, v0.0.11) may subtly change build behavior, introduce new features, or require updated Docker daemon capabilities. Always test new versions in a non-production environment first.fixReview release notes for changes in `buildx` versions. Ensure your Docker daemon is compatible with the `buildx` version used by the provider, and test your build process.
affects: All versions, especially with major BuildKit updates.
gotchaSome advanced features, like specifying multiple exports for an image build, require BuildKit daemon version 0.13 or newer. Using these features with an older daemon will result in an error.fixEnsure your Docker daemon has BuildKit version 0.13 or newer enabled. Check Docker Desktop settings or update your Docker Engine installation.
affects: <=0.0.7
gotchaIncorrect or missing Docker registry authentication details can prevent images from being pushed. This is a common pitfall when working with private registries or Docker Hub.fixEnsure `ImageRegistryArgs` are correctly configured with valid `server`, `username`, and `password` (e.g., from environment variables like `DOCKER_USERNAME`, `DOCKER_PASSWORD`). Alternatively, ensure your Docker client is logged in via `docker login` before `pulumi up`.
affects: All versions
gotchaOlder versions (pre-0.0.11) had an issue where upgrading `pulumi-docker-build` itself could unintentionally cause `Image` resources to be replaced, leading to downtime or re-pushes. While a specific instance was fixed in v0.0.11, always review `pulumi up` previews carefully for unexpected replacements.fixAlways review `pulumi up` previews for unexpected resource replacements. If observed, investigate the cause or pin to an older provider version temporarily. Upgrading to v0.0.11+ is recommended.
affects: <=0.0.10
gotchaRefreshing `Index` resources (used for multi-architecture images) might fail if the stored credentials for the associated registry have expired. This can lead to issues with maintaining multi-arch manifests.fixFor long-lived deployments, ensure registry tokens used for `Index` resources have sufficient validity or implement a mechanism to re-authenticate as needed. Upgrading to v0.0.7+ resolves some refresh issues.
affects: <=0.0.6
Upgrade
Version history
0.0.18latest on PyPI · released May 27, 2026
Audit
Dependencies
No dependency data recorded yet.