pulumi/pulumi

Configuration

This page collects the configuration knobs that affect both end users and contributors.

Project-level: `Pulumi.yaml`

Lives at the root of every Pulumi project. Defined by the schema in sdk/go/common/workspace/.

name: my-app
runtime:
  name: nodejs # nodejs | python | go | dotnet | java | yaml | pcl
  options:
    typescript: true
description: An example
main: ./src/index.ts # entry point (override default)
config:
  aws:region: us-east-1
plugins: # explicit plugin pins (rare)
  providers:
    - name: aws
      version: 6.10.0
options:
  refresh: always # implicit refresh on `up`
backend:
  url: https://api.pulumi.com # or s3://my-bucket, file://~, etc.
template: # for `pulumi new` template projects
  description: ...

Stack-level: `Pulumi.<stack>.yaml`

Per-stack config, encrypted secrets, and overrides:

config:
  aws:region: us-east-1
  myapp:dbPassword:
    secure: v1:abc123:base64ciphertext
encryptionsalt: v1:salt-base64:provider-state
secretsprovider: passphrase

Secrets are encrypted by the configured secretsprovider. See systems/secrets.

Environment variables

Common ones the CLI reads:

Variable	Effect
`PULUMI_ACCESS_TOKEN`	Pulumi Cloud bearer token
`PULUMI_BACKEND_URL`	Override backend URL
`PULUMI_CONFIG_PASSPHRASE`	Passphrase for the passphrase secrets provider
`PULUMI_CONFIG_PASSPHRASE_FILE`	File-based passphrase
`PULUMI_PLUGINS_DIR`	Override plugin cache dir
`PULUMI_HOME`	Override `~/.pulumi` location
`PULUMI_DEBUG_COMMANDS`	Expose hidden CLI commands
`PULUMI_DEBUG_GRPC`	Path for gRPC trace dump
`PULUMI_DISABLE_VALIDATION`	Skip snapshot integrity check (dangerous)
`PULUMI_SKIP_UPDATE_CHECK`	Don't poll for new CLI versions
`PULUMI_PYTHON_DEBUG`	Enable Python host debug behavior
`NODE_OPTIONS`	Node-host runtime flags (e.g. `--inspect-brk`)
`PULUMI_ACCEPT`	In tests: regenerate golden fixtures
`LIFECYCLE_TEST_FUZZ_CHECKS`	Override fuzz iterations in lifecycle tests
`PULUMI_VERSION`	Override the version reported by the CLI
`SDKS`	Subset of SDKs to build (`make build SDKS="nodejs python"`)
`GOLANGCI_LINT_ARGS`	Extra flags for golangci-lint (`make lint`)

The complete env catalog lives in sdk/go/common/env/ (typed bindings) and pkg/cmd/pulumi/env/ (CLI surface).

CLI global flags

Apply to most commands:

Flag	Purpose
`--cwd`	Run as if from a different working dir
`--non-interactive`	Disable prompts
`--color {always,auto,never,raw}`	Color rendering
`--logtostderr`	Send glog output to stderr
`-v=N`	glog verbosity (most useful: 9, 11)
`--logflow`	Propagate verbosity to plugins
`--profiling=<file>`	pprof profile output
`--tracing=<endpoint>`	OpenTelemetry tracing
`--emoji=false`	Disable emoji output
`--disable-integrity-checking`	Bypass snapshot validation (dangerous)

Backend-specific config

DIY (`pkg/backend/diy/`)

Backend URL examples:

file://~/.pulumi          # local FS at default
file:///abs/path/         # local FS, explicit
s3://my-bucket            # S3
s3://my-bucket?region=us-east-1
gs://my-bucket            # GCS
azblob://my-container     # Azure Blob

Authentication uses the standard SDK chain for each cloud (e.g. AWS_PROFILE, AZURE_CLIENT_ID).

Pulumi Cloud (`httpstate`)

https://api.pulumi.com    # default

Self-hosted Pulumi Cloud instances use their own URL. Auth is via PULUMI_ACCESS_TOKEN or pulumi login.

Tool versions (`.mise.toml`)

Pinned at the repo root. Excerpt:

go = "1.25"
node = "20"
python = '3.11'
dotnet = "8"
protoc = "29.5"
golangci-lint = "2.9.0"
gofumpt = "latest"
uv = "0.10.0"
"go:google.golang.org/protobuf/cmd/protoc-gen-go" = "v1.36.6"
"go:google.golang.org/grpc/cmd/protoc-gen-go-grpc" = "v1.5.1"

If you change a pinned version, also bump it in any CI matrix (.github/workflows/ci-info.yml).

Build configuration

Top-level Makefile variables:

Variable	Default	Purpose
`SDKS`	`nodejs python go pcl`	Which SDKs to build
`LIFECYCLE_TEST_FUZZ_CHECKS`	`10000`	Fuzz iterations
`TEST_ALL_DEPS`	builds all SDKs	Override with empty to skip deps
`LINT_GOLANG_PKGS`	`sdk pkg tests sdk/go/pulumi-language-go ...`	Modules to lint
`GOLANGCI_LINT_ARGS`	``	Pass-through to golangci-lint
`PULUMI_VERSION`	from `scripts/pulumi-version.sh`	Override version

Schema metaschema

pkg/codegen/schema/pulumi.json — the JSON Schema for provider schemas. Validate with:

make lint_pulumi_json

Provider schemas live in their own repos (e.g. pulumi-aws/provider/cmd/pulumi-resource-aws/schema.json).