Ready to level-up your engineering skills? Join a Pulumi Workshop. Register Now


A Pulumi project is any folder which contains a Pulumi.yaml file. When in a subfolder, the closest enclosing folder with a Pulumi.yaml file determines the current project. A new project can be created with pulumi new. A project specifies which runtime to use, which determines where to look for the program that should be executed during deployments. Supported runtimes are nodejs, python, dotnet, and go.

Project file

The Pulumi.yaml project file specifies metadata about your project.

This file must begin with a capitalized P, although either .yml or .yaml extension will work.

A typical Pulumi.yaml file looks like the following:

name: webserver
runtime: nodejs
description: Basic example of an AWS web server accessible over HTTP.

A project file contains the following attributes:

  • name: (required) a name for your project. This shows up in the Pulumi dashboard and is used to aggregate the associated stacks and their resources underneath the project, as a simple kind of hierarchy. Project names may only contain alphanumeric characters, hyphens, underscores, or periods.

  • runtime: (required) (string|object) the language runtime configuration to use for your program. Possible string options are nodejs (for JavaScript and TypeScript), python (for Python),go (for Go), and dotnet (for .NET). At the moment, Pulumi doesn’t depend on specific versions of these runtimes, and will simply use whatever version you have installed on your machine.

    • name: runtime can either be specified as a string, or a complex object with additional configuration. If you need to include additional configuration, specify language information (nodejs, python, go, or dotnet) in this property.
    • options: (optional) a property bag that has various configuration options that apply to different language runtimes.
      • typescript: applies to Node.js projects only. A boolean (true | false) controls whether to use ts-node to execute sources. Defaults to true.
      • binary: applies to Go and .NET projects only
        • Go: A string that specifies the name of a pre-built executable to look for on your path. If not specified, go sources in $CWD will be invoked via go run.
        • .NET: A string that specifies the path of a pre-built .NET assembly. If not specified, a .NET project in $CWD will be invoked via dotnet run.
      • virtualenv: applies to Python projects only. A string that specifies the path to a virtual environment to use when running the program. 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. If you’d like to use a virtual environment without the virtualenv option, you’ll need to run any pulumi commands (such as pulumi up) from an activated virtual environment shell (or, if using a tool like Pipenv, prefix any pulumi commands with pipenv run pulumi ...).
  • description: (optional) a friendly description about your project.

  • main: (optional) an override for the main program’s location. By default, the program’s working directory is assumed to be the location of Pulumi.yaml. To choose a different location, use the main property. For example, if your Pulumi program is in a subdirectory infra/, use main: infra/.

  • config: (optional) directory to store stack-specific configuration files, relative to location of Pulumi.yaml.

  • backend: (optional) configuration for project state backend. Supports these options:

    • url: explicitly specify backend url like, file:///app/data, etc.
  • template: (optional) provides configuration settings that will be used when initializing a new stack from a project file using pulumi new. Currently these values are only used by pulumi new, and not by pulumi stack init or as default configuration for existing stacks.

    • description: (optional) a description for the template itself.
    • config: (required) the map of configuration values keyed by the name of the config setting - such as aws:region. The value of each key includes:
      • description: (optional) a description for the config setting.
      • default: (optional) the default value of the config setting - which will be presented to the user as a default.
      • secret: (optional) if true indicates that this configration value should be marked as secret.

When using JavaScript, the working directory for the project should contain a package.json that points to a file such as index.js. In Python, there should either be a file or a file that defines the entry point.

A Pulumi.yaml file for a nodejs program that does not execute TypeScript natively via ts-node:

name: minimal
description: A minimal Pulumi program.
  name: nodejs
    typescript: false

A Pulumi.yaml file for a go program that will only use a pre-built executable by the name mybinary:

name: ls
    name: go
        binary: mybinary
description: A minimal Go Pulumi program

A Pulumi.yaml file for a dotnet program that will use a pre-built assembly MyInfra.dll under the bin directory:

name: ls
    name: dotnet
        binary: bin/MyInfra.dll
description: A precompiled .NET Pulumi program


When your Pulumi program references resources in the local filesystem, they are always relative to the working directory. The following example code references a subfolder app of the working directory, which would contain a Dockerfile and application code:

const myTask = new cloud.Task("myTask", {
    build: "./app", // subfolder of working directory
const myTask = new cloud.Task("myTask", {
    build: "./app", // subfolder of working directory
myTask = Task('myTask',
        'build': './app' # subfolder of working directory
var myTask = new Task("myTask", new TaskArgs
    Build = "./app", // subfolder of working directory

Stack Settings Files

Each stack that is created in a project will have a file named Pulumi.<stackname>.yaml which contains the configuration specific to this stack.

For stacks that are actively developed by multiple members of a team, the recommended practice is to check them into source control as a means of collaboration. Since secret values are encrypted, it is safe to check in these stack settings.

For stacks that are ephemeral or are used in “inner loop” development, the stack settings are typically not checked into source control.

For more information about configuration and how this file is managed using the CLI and programming model, refer to Configuration and Secrets.