pulumi/pulumi

Python SDK

Active contributors: Justin Van Patten, Thomas Gummerer, Julien

Purpose

sdk/python/ is the Python SDK published as pulumi on PyPI. It supports all Python versions tracked by devguide.python.org/versions.

Directory layout

sdk/python/
├── lib/pulumi/                 # The actual package (importable as `pulumi`)
│   ├── __init__.py             # Public re-exports
│   ├── resource.py             # Resource hierarchy (≈54 KB)
│   ├── output.py               # Output[T], Input[T] (≈40 KB)
│   ├── config.py               # pulumi.Config (≈25 KB)
│   ├── invoke.py               # invoke()
│   ├── errors.py               # PulumiError + subclasses
│   ├── log.py                  # pulumi.log
│   ├── stack_reference.py      # StackReference
│   ├── stash.py                # Per-context state
│   ├── _types.py               # Type helpers (≈40 KB)
│   ├── _utils.py               # Generic helpers
│   ├── metadata.py             # get_stack(), get_project()
│   ├── asset.py                # Asset / Archive
│   ├── urn.py                  # URN type
│   ├── deprecated.py           # @deprecated decorator
│   ├── type_token.py           # tokens.Type wrapper
│   ├── automation/             # Automation API
│   ├── policy/                 # Policy-pack scaffolding
│   ├── provider/               # Provider authoring (Construct/Call)
│   ├── runtime/                # gRPC client + monitor (the engine bridge)
│   └── dynamic/                # Dynamic providers
├── cmd/pulumi-language-python/ # The Python language host (Go binary)
├── toolchain/                  # pip / poetry / uv abstraction
├── tools/automation/           # Automation API codegen
├── pyproject.toml
└── pytest.ini

Key abstractions

Symbol	File	Role
`Resource`, `CustomResource`, `ComponentResource`, `ProviderResource`	`lib/pulumi/resource.py`	Inheritance hierarchy
`Output[T]`, `Input[T]`	`lib/pulumi/output.py`	Future-like type with dependency tracking
`output(value)`	`lib/pulumi/output.py`	Lift a value to an Output
`Output.all(*outputs)`	`lib/pulumi/output.py`	Combine outputs
`Config`	`lib/pulumi/config.py`	Stack config reader
`StackReference`	`lib/pulumi/stack_reference.py`	Cross-stack outputs
`pulumi.runtime.Mocks`	`lib/pulumi/runtime/mocks.py`	Test harness
`pulumi.dynamic.Resource`	`lib/pulumi/dynamic/`	In-program providers

Async semantics

Python's Output is built on asyncio.Future. Output.apply(fn) returns a new Output; the callback may be sync or async. Internally, the SDK runs an event loop driven by the language host.

url = bucket.bucket.apply(lambda b: f"https://{b}.s3.amazonaws.com/")

Outputs are awaitable via .future() — useful in tests and Automation-API contexts.

Unlike Node and Go, Python projects come in many flavors: plain pip + venv, poetry, uv. sdk/python/toolchain/ abstracts over them so the language host can install dependencies in the user's preferred way. The choice is driven by runtime.options.toolchain in Pulumi.yaml:

runtime:
  name: python
  options:
    toolchain: poetry

Supported toolchains as of the latest release: pip, poetry, uv.

Type helpers

lib/pulumi/_types.py (~40 KB) is the SDK's flavor of typing helpers. It supports generic Output[T] shapes, Input[T], and the @input_type / @output_type decorators that provider-generated SDKs use.

Build

sdk/python/Makefile runs uv (the pinned package manager from .mise.toml) for all build/test/install operations. make build produces a wheel; make test_fast runs pytest.

Linting

ruff (configured in pyproject.toml) is the only Python linter. make lint_fix auto-fixes.

Tests

lib/pulumi/automation/...test*.py — Automation API tests.
pulumi/runtime/...test*.py — runtime layer.
The conformance suite (scripts/run-conformance.sh) cross-tests Python against Go and Node.

Dynamic providers — `lib/pulumi/dynamic/`

Just like Node, Python supports dynamic providers. Pickle is used to serialize the provider class so the host can run it. Be aware that pickle has version-compatibility caveats — the Python version that runs the provider must be able to unpickle whatever the creating version produced.

Entry points for modification

Public API change — lib/pulumi/__init__.py and the relevant module. Watch out for type stubs (_types.py).
Async change — lib/pulumi/runtime/. The whole SDK has been async-clean since 3.x; please don't introduce blocking calls.
Toolchain support — toolchain/ is the pluggable layer.