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

Pulumi project file reference

    Every Pulumi program has a project file, Pulumi.yaml, which specifies metadata about your project, such as the project name and language runtime. The project file must begin with a capital P and have an extension of either .yml or .yaml. For more information about Pulumi projects, see the following Pulumi projects overview.

    For Pulumi programs specifically written in Pulumi YAML, the project file not only serves as a configuration and metadata repository but also contains the program’s infrastructure definition itself. To learn more, see Pulumi YAML.


    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, relative to the location of Pulumi.yaml. The default is the current 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

    About main

    For all languages, main can point to a directory to have Pulumi load the program from that directory instead of the directory containing Pulumi.yaml.

    Some languages also support using main to point to a specific file to change what the runtime considers the program entrypoint.

    • For Node.js projects, main can point to a .ts or .js file and behaves similarly to setting the main attribute in package.json. When the main property is set in Pulumi.yaml, it may be omitted from package.json (and vice-versa). When it exists in both Pulumi.yaml and package.json, the value in Pulumi.yaml takes precedence.

    • For Python projects, main can point to a module file (e.g., example.py) and the file will be passed to python.

    • For .NET projects, main can point to a .NET project file (e.g., example.csproj) and the file will be passed to dotnet run.

    For all other languages, the actual filename is ignored, and the system behaves as though main referred to the file’s containing directory.

    runtime options

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

    NameUse caseDescription
    typescriptOnly applies to the nodejs runtimeBoolean indicating whether to use ts-node or not.
    nodeargsOnly applies to the nodejs runtimeArguments to pass to node.
    buildTargetOnly applies to the go runtimePath to save the compiled go binary to.
    binaryapplies to the go, dotnet, and java runtimesPath to a pre-built executable.
    virtualenvOnly applies to the python runtimeVirtual environment path.
    typecheckerOnly applies to the python runtimeType checker library to use.
    compilerOnly applies to the yaml runtimeExecutable 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 with go build to the specified path before being run.
      • If unspecified, Go sources in $CWD will be compiled with 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 with 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 ....

    About typechecker

    This option can be set to mypy or pyright. (For additional type checkers, file an issue at https://github.com/pulumi/pulumi/issues.). If set, the given type checker will be invoked to check the Python code before running the Pulumi program.

    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.


    valuerequiredThe value of this configuration property.


    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.

    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

    urloptionalURL is optional field to explicitly set backend url.

    options options

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

    template options

    displayNameoptionalA user-friendly name for the template. This should follow Title Case format and be succinct. This field is only supported by Pulumi CLI >= 3.95.
    descriptionoptionalDescription of the template.
    configrequiredConfig to request when using this template with pulumi new.
    metadataoptionalA map of user-defined tags to attach to the template. This field is only supported by Pulumi CLI >= 3.95.


    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.

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

    Options for providers, analyzers, and languages

    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

    configoptionalConfig directory relative to the location of Pulumi.yaml.

    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/
      url: https://pulumi.example.com
      refresh: always
      displayName: Example Template
      description: An example template
          description: The AWS region to deploy into
          default: us-east-1
          secret: true
        cloud: aws
        - name: aws
          path: ../../bin
        - name: yaml
          path: ../../../pulumi-yaml/bin
          version: 1.2.3
      Introducing Pulumi Copilot - Intelligent Cloud Management