1. Docs
  2. Concepts
  3. Projects
  4. Project file

Pulumi project file

The Pulumi.yaml project file specifies metadata about your project, such as the project name and language runtime for your project.

Example project files

Example project file with only required attributes

name: Example Pulumi project file with only required attributes
runtime: nodejs

Example project file with all possible attributes

name: Example Pulumi project file with all possible attributes
runtime: yaml
description: An example project with all attributes
main: example-project/
stackConfigDir: config/
backend:
  url: https://pulumi.example.com
options:
  refresh: always
template:
  description: An example template
  config:
    aws:region:
      description: The AWS region to deploy into
      default: us-east-1
      secret: true
plugins:
  providers:
    - name: aws
      path: ../../bin
  languages:
    - name: yaml
      path: ../../../pulumi-yaml/bin
      version: 1.2.3

Attributes

All attributes

NameRequiredDescriptionOptions
namerequiredName of the project containing alphanumeric characters, hyphens, underscores, and periods.None.
runtimerequiredInstalled language runtime of the project: nodejs, python, go, dotnet, java or yaml.runtime options
descriptionoptionalA brief description of the project.None.
configoptionalProject level config (Added in v3.44).config options
mainoptionalPath to the Pulumi program. The default is the working directory.None.
stackConfigDiroptionalConfig directory location relative to the location of Pulumi.yaml.None.
backendoptionalBackend of the project.backend options
optionsoptionalAdditional project options.options options
templateoptionalConfig to be used when creating new stacks in the project.template options
pluginsoptionalOverride for the plugin selection. Intended for use in developing pulumi plugins.plugins options

runtime options

The runtime attribute has an additional property called options where you can further specify runtime configuration.

NameUse caseDescription
typescriptOnly applicable for the nodejs runtimeBoolean indicating whether to use ts-node or not.
nodeargsOnly applicable for the nodejs runtimeArguments to pass to node.
buildTargetOnly applicable for the go runtimePath to save the compiled go binary to.
binaryApplicable for the go, .net, and java runtimesPath to pre-built executable.
virtualenvOny applicable for the python runtimeVirtual environment path.
compilerOnly applicable for YAML projectsExecutable and arguments issued to standard out.

About nodeargs

Arguments specified here are passed to node when running the Pulumi program. For example, nodeargs: "--trace-warnings" will result in node being invoked as node --trace-warnings.

About buildTarget

  • For Go
    • If specified, go sources in $CWD will be compiled via go build to the specified path before being run.
    • If unspecified, go sources in $CWD will be compiled via go build to a temporary executable that is deleted after running.
    • Cannot be specified with the binary runtime option.

About binary

  • For Go, cannot be specified with the buildTarget runtime option.
  • For .NET, if not specified, a .NET project in $CWD will be invoked via dotnet run.

About virtualenv

New Python projects created with pulumi new have this option set by default. If not specified, Pulumi will invoke the python3 command it finds on $PATH (falling back to python) to run the Python program. To use a virtual environment without the virtualenv option, run pulumi commands (such as pulumi up) from an activated virtual environment shell. Or, if using a tool like Pipenv, prefix pulumi commands with pipenv run pulumi ....

config options

config is a map of config property keys to either values or structured declarations.

Non-object values are allowed to be set directly. Anything more complex must be defined using the structured schema declaration, or the nested value declaration both shown below.

Values

NameRequiredDescription
valuerequiredThe value of this configuration property.

Schemas

Schemas are only valid for project property keys. For setting the value of a provider configuration either use a direct value, or the nested value declaration shown above.

NameRequiredDescription
typerequiredThe type of this config property, either string, boolean, integer, or array.
descriptionoptionalA description for this config property.
secretoptionalTrue if this config property should be a secure secret value.
defaultoptionalThe default value for this config property, must match the given type.
itemsrequired if type is arrayA nested structured declaration of the type of the items in the array.

backend options

NameRequiredDescription
urloptionalURL is optional field to explicitly set backend url.

options options

NameRequiredDescription
refreshoptionalSet to always to refresh the state before performing a Pulumi operation.

template options

NameRequiredDescription
descriptionoptionalDescription of the template.
configrequiredConfig to request when using this template with pulumi new.

config

NameRequiredDescription
descriptionoptionalDescription of the config.
defaultoptionalDefault value of the config.
secretoptionalBoolean indicating if the configuration is labeled as a secret.

plugins options

Use this option to link to local plugin binaries. This option is intended for use in developing pulumi plugins.

NameRequiredDescription
providersoptionalList of provider plugins.
analyzersoptionalList of policy plugins.
languagesoptionalList of language plugins.

Options for providers, analyzers, and languages

NameRequiredDescription
namerequiredName of the plugin.
pathoptionalPath to the plugin folder.
versionoptionalVersion of the plugin, if not set, will match any version the engine requests.

Deprecated attributes

NameRequiredDescription
configoptionalConfig directory relative to the location of Pulumi.yaml.