pulumi/pulumi

Getting started

This page walks through cloning, building, and running Pulumi from source. It is aimed at platform contributors. End-users should follow pulumi.com/docs/install instead.

Prerequisites

Tool versions are pinned in .mise.toml. The recommended setup is to install mise and let it manage everything:

# install mise (https://mise.jdx.dev/getting-started.html)
mise install            # reads .mise.toml, installs Go, Node, Python, protoc, ...
mise activate           # add to your shell profile, then re-source

If mise is not on your PATH after activation, prefix every make command with mise exec --. The AGENTS.md at the repo root spells this out.

The pinned versions (from .mise.toml) at the time of writing:

Tool	Version
go	1.25
node	20
python	3.11
dotnet	8
protoc	29.5
golangci-lint	2.9.0
uv	0.10.0
bun	latest
typescript	latest

You also need a working make, git, and bash. The build is supported on Linux and macOS; Windows works via WSL.

Clone and bootstrap

git clone https://github.com/pulumi/pulumi.git
cd pulumi
mise install                       # installs the toolchain into ~/.local/share/mise
make ensure                        # downloads Go modules for sdk/, pkg/, tests/

make ensure is also a prerequisite for running anything else.

Build

The default make build builds the CLI plus all four SDKs in this repo (nodejs, python, go, pcl). For a faster inner loop you can build only what you need:

make build                         # CLI + all SDKs
SDKS="nodejs python" make build    # CLI + selected SDKs
make bin/pulumi                    # CLI only (no SDKs)

The CLI binary lands at bin/pulumi. Add bin/ to your PATH before running integration tests — they call out to pulumi and rely on finding it.

For local SDK development, the build installs into $HOME/.dev-pulumi. Add that to your PATH to use the freshly built SDKs from your own Pulumi programs.

Run from source

./bin/pulumi version              # confirm it built
./bin/pulumi login --local        # use the DIY (filesystem) backend
mkdir myproj && cd myproj
../bin/pulumi new typescript
../bin/pulumi up

The DIY backend writes state under ~/.pulumi/. To use Pulumi Cloud instead, run pulumi login without --local.

Run the tests

The Go test ecosystem is broken into "fast" tests (no plugins, no real cloud) and "all" tests (which require building the CLI and SDKs first):

make test_fast                     # quick, no infrastructure dependencies
make test_all                      # full suite — slow, expects bin/pulumi on PATH
./scripts/run-conformance.sh       # cross-language conformance suite

For Go integration tests across the whole tree:

cd pkg && go test -count=1 -tags all ./codegen/go/...

For a single package, add -run TestSomething and -v. Tests use Rapid (pgregory.net/rapid) for property-based fuzzing of the deployment lifecycle (pkg/engine/lifecycletest/); the fuzz iteration count is controlled by LIFECYCLE_TEST_FUZZ_CHECKS in the Makefile (default 10,000).

Lint and format

Linting and formatting are required before opening a PR. CI rejects PRs that fail.

make lint                          # golangci-lint, biome, eslint, ruff
make lint_fix                      # auto-fix what can be fixed
make format                        # gofumpt + biome format
make tidy                          # check go.mod/go.sum across all modules
make tidy_fix                      # tidy each module

Formatting is gofumpt for Go and biome for Node/JS/TS/JSON.

Protobufs

Generated proto code lives at sdk/proto/go/, sdk/nodejs/proto/, and sdk/python/lib/pulumi/runtime/proto/. To regenerate:

make build_proto                   # regenerate from proto/*.proto
make check_proto                   # CI version: fail if out of sync

Never edit generated files by hand — edit the .proto source instead.

Changelog entries

Every PR (other than impact/no-changelog-required) needs a changelog entry under changelog/pending/:

make changelog                     # interactive — prompts for type, scope, message

The type/scope vocabulary is defined in changelog/config.yaml (feat, fix, chore; scopes like cli/state, sdk/python, sdkgen/go, etc.).

Common make targets cheat sheet

Goal	Command
Build CLI + SDKs	`make build`
Build CLI only	`make bin/pulumi`
Single SDK	`cd sdk/nodejs && make build`
Quick tests	`make test_fast`
Full tests	`make test_all`
Lint	`make lint`
Format	`make format`
Regenerate protos	`make build_proto`
Tidy go modules	`make tidy`
Go workspace	`make work` (creates `go.work`)

For sub-package specifics see the per-directory AGENTS.md files (pkg/AGENTS.md, sdk/nodejs/AGENTS.md, etc.).