Plugins

Plugins are Pulumi’s core extensibility mechanism, allowing the Pulumi engine to communicate in a uniform manner with various languages, resource providers, and other tools. Plugins always run as separate processes and mostly use gRPC for communication with the Pulumi engine.

Plugin types

Pulumi supports five categories of plugins:

Resource plugins

Resource plugins (also known as providers) expose standardized interfaces for managing cloud resources. Resource plugins are distributed as Pulumi packages. A listing of providers is available in the Pulumi Registry.

In addition to the packages in the Pulumi Registry, you can write your own components and distribute them as resource plugins, enabling consumption in any Pulumi language. Components can be published to Pulumi IDP for discoverability within your organization or shared directly via Git references.

When you first run pulumi preview or pulumi up, the Pulumi CLI will install any required providers that are not already in your plugin cache.

Language plugins

Language plugins (also known as language hosts) host programs written in specific languages, enabling the Pulumi engine to execute your Pulumi code without understanding language-specific details. As described in How Pulumi works, language plugins consist of:

1. A language executor binary named pulumi-language-<language-name>, which Pulumi uses to launch the runtime for your program’s language (e.g., Node.js or Python). This binary is distributed with the Pulumi CLI.
2. For all languages except YAML, a language SDK that prepares your program for execution and observes resource registrations.

Pulumi-supported language plugins are installed automatically with the Pulumi CLI. Community-supported language plugins can be installed separately.

Analyzer plugins

Analyzer plugins scan Pulumi programs for potential issues and power Pulumi Policy as Code. These plugins enable you to enforce compliance, security, and best practices across your infrastructure.

Policy plugins are installed automatically with the Pulumi CLI.

Converter plugins

Converter plugins transform existing infrastructure-as-code from other tools (like Terraform, Kubernetes YAML, or CloudFormation) into Pulumi programs. Learn more about converters.

Converter plugins are installed automatically with the Pulumi CLI when you run the pulumi convert command.

Tool plugins

Tool plugins enable integration between Pulumi and external tools, extending Pulumi’s capabilities to work with your existing workflows and toolchains.

Plugin installation and management

Automatic installation

The Pulumi CLI normally handles plugin installation automatically. For example:

• Resource plugins (provider binaries) are installed automatically when you first run pulumi preview or pulumi up if they are not already present in the plugin cache
• Language plugins are installed with the Pulumi CLI
• Policy plugins are installed with the Pulumi CLI
• The Pulumi CLI ensures your resource plugins are present when you run your Pulumi program

Manual installation

Most users will not need to run the pulumi plugin install command manually. However, manual plugin installation can be useful for scenarios like:

• Pre-loading plugins on a custom Docker image to speed up CI/CD pipelines
• Working in air-gapped environments
• Testing pre-release versions of plugins
• Installing plugins that are community-maintained

Plugin storage

Plugins are stored in different locations depending on their type:

• All plugins that ship with the Pulumi CLI, including all of our supported Language plugins and policy plugins are stored in ~/.pulumi/bin
• All plugins that are installed by the user, whether explicitly or automatically by the Pulumi CLI, are cached in ~/.pulumi/plugins

Plugin management commands

You can manage your local plugin cache using the following CLI commands:

• pulumi plugin ls - List installed plugins
• pulumi plugin rm - Remove cached plugins
• pulumi plugin install - Manually install a plugin

Plugin implementation details

Plugins are deployed through two approaches:

• Executables following the naming convention pulumi-<kind>-<name> (e.g., pulumi-resource-aws)
• Source-based plugins containing a PulumiPlugin.yaml configuration file, where the engine uses the specified runtime to execute the plugin through the language plugin’s interface

For more details about Pulumi plugin architecture and how to contribute to plugin development, see the Pulumi Developer Documentation.

PulumiPlugin.yaml reference

Source-based plugins use a PulumiPlugin.yaml file to configure how the plugin runs. The filename is case-sensitive: it must be exactly PulumiPlugin.yaml or PulumiPlugin.yml.

Use this configuration file when developing custom components or providers to distribute as plugins. Most Pulumi users working with standard programs will not need to create or modify a PulumiPlugin.yaml file.

Attributes

Plugin runtime options

The runtime attribute can be specified as a simple string or as an object with additional options. When using the object form, name is required and takes the same values as the string form. Not all runtime options from Pulumi.yaml are supported for plugins.

Simple runtime specification

runtime: nodejs

Runtime with options

runtime:
  name: nodejs
  options:
    packagemanager: yarn

Node.js runtime options

Python runtime options

Go runtime options

Go plugins do not support any runtime options.

.NET runtime options

Java runtime options

YAML runtime options

YAML plugins do not support any runtime options.

Example plugin files

Python plugin with virtual environment

runtime:
  name: python
  options:
    toolchain: uv
    virtualenv: venv

.NET plugin with custom binary path

runtime:
  name: dotnet
  options:
    use-executor: /opt/homebrew/bin/dotnet

Plugin with version requirement

runtime: nodejs
requiredPulumiVersion: ">=3.100.0"

Related topics

• Providers - Learn more about resource plugins (providers)
• How Pulumi works - Understand how plugins fit into Pulumi’s architecture