1. Docs
  2. Pulumi IaC
  3. Languages & SDKs
  4. Python

Pulumi & Python

    Pulumi supports writing your infrastructure as code in the Python language running on any supported version.

    Install Python. To reduce potential issues with setting up your Python environment on Windows or macOS, you should install Python through the official Python installer.

    Either pip, poetry or uv is required to install dependencies. If you installed Python from source, with an installer from python.org, or via Homebrew you should already have pip. If Python is installed using your OS package manager, you may have to install pip separately, see Installing pip/setuptools/wheel with Linux Package Managers. For example, on Debian/Ubuntu you must run sudo apt install python3-venv python3-pip. To install poetry follow the installation instructions. To install uv follow the installation instructions.

    If you're having trouble setting up Python on your machine, see Python 3 Installation & Setup Guide for detailed installation instructions on various operating systems and distributions.

    Pulumi Programming Model

    The Pulumi programming model defines the core concepts you will use when creating infrastructure as code programs using Pulumi. Concepts describes these concepts with examples available in Python. These concepts are made available to you in the Pulumi SDK.

    The Pulumi SDK is available to Python developers as a package distributed on PyPI. To learn more, refer to the Pulumi SDK Reference Guide.

    Inputs and Outputs

    The Pulumi programming model includes a core concept of Input and Output values, which are used to track how outputs of one resource flow in as inputs to another resource. This concept is important to understand when getting started with Python and Pulumi, and the Inputs and Outputs documentation is recommended to get a feel for how to work with this core part of Pulumi in common cases.

    In Python, inputs that are objects, that is inputs that group multiple values together, can be represented either as classes or as dictionary literals. The types for the argument classes have the suffix Args, whereas the types for the dictionaries have the suffix ArgsDict. Both types take the same arguments, but the dictionary types are often more concise.

    The types with the suffix ArgsDict for dictionary literals were introduced in July 2024. You can still use dictionary literals with providers that have not been updated yet with this change, but you will not benefit from the type checking that the new types provide.

    This example shows two ways to create an ecr.Repository resource in Python, once using a dictionary literal and once using a class:

    import pulumi_aws as aws
    
    repo1 = aws.ecr.Repository("repo1-with-dictionary-literals",
        image_tag_mutability="MUTABLE",
        image_scanning_configuration={
            "scan_on_push": True,
        })
    
    repo2 = aws.ecr.Repository("repo2-with-args",
        image_tag_mutability="MUTABLE",
        image_scanning_configuration=aws.ecr.RepositoryImageScanningConfigurationArgs(
            scan_on_push=True
        ))
    

    Blocking and Asynchronous Code

    A Python Pulumi program is single threaded and the Pulumi runtime creates an event loop to enable the runtime to be asynchronous.

    Given these constraints, Blocking and Async Python with Pulumi gives some recommendations on using blocking and asynchronous code within Python Pulumi programs.

    Using Pulumi PyPI Packages

    Virtual Environments

    It is not required, but we recommend using a virtual environment to isolate the dependencies of your projects and ensure reproducibility between machines.

    When creating a new Python project with pulumi new, you are offered the choice between pip (default), poetry and uv to manage your dependencies. You can also change this at any time by updating the toolchain option in Pulumi.yaml. Existing Python projects that do not use a virtual environment can opt-in to using the built-in virtual environment support by setting the option and then running pulumi install to create the virtual environment and install dependencies.

    Pip

    When using pip Pulumi will create a virtual environment and install the required dependencies from requirements.txt. The virtualenv option is required for pip and controls the name of the virtual environment directory.

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

    Poetry

    When using poetry Pulumi will run Poetry to create a virtual environment in its default location and install the required dependencies from pyproject.toml. When no pyproject.toml file is present, Pulumi will look for a requirements.txt file and convert it to a pyproject.toml file.

    Pulumi requires Poetry version 1.8.0 or later.

    runtime:
      name: python
      options:
        toolchain: poetry
    

    To further configure poetry, you can provide a poetry.toml configuration file in the project directory.

    Uv

    When using uv Pulumi will create a virtual environment in the .venv directory and install the required dependencies from pyproject.toml. When no pyproject.toml file is present, Pulumi will look for a requirements.txt file and convert it to a pyproject.toml file. The virtualenv option controls the name of the virtual environment directory. This is optional for uv and defaults to .venv.

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

    Self managed virtual environments

    If you prefer to manage the virtual environment on your own (for example, using a tool like Pipenv), you can delete the local venv directory and unset the virtualenv option in Pulumi.yaml:

    runtime: python
    

    When managing the virtual environment on your own, 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 ...).

    Type Checking

    Pulumi Python libraries ship with type hints. You can manually run a type checking system of your choice when developing with Pulumi to make use of these type hints. As of 3.113.0 Pulumi also has first class support for mypy and pyright when running your program.

    This behavior is controlled by the following typechecker runtime option in Pulumi.yaml:

    runtime:
      name: python
      options:
        typechecker: mypy
    

    When set, Pulumi will invoke the type checker before running your program. This can be used to ensure your program is always type safe when running pulumi up without you having to remember to run a separate checking command beforehand.

    Adding a new dependency

    There are many Pulumi Python packages available.

    Pip

    To install a new dependency in the virtual environment when using pip, add an entry to requirements.txt, and run the following in your project directory:

    $ venv/bin/pip install -r requirements.txt
    
    $ venv/bin/pip install -r requirements.txt
    
    > venv\Scripts\pip install -r requirements.txt
    

    Poetry

    To add a new dependency when using poetry, run the poetry add command in your project directory. The dependency will be added to the pyproject.toml file and installed in the virtual environment:

    $ poetry add ${PACKAGE_NAME}
    
    $ poetry add ${PACKAGE_NAME}
    
    > poetry add ${PACKAGE_NAME}
    

    Uv

    To add a new dependency when using uv, run the uv add command in your project directory. The dependency will be added to the pyproject.toml file and installed in the virtual environment:

    $ uv add ${PACKAGE_NAME}
    
    $ uv add ${PACKAGE_NAME}
    
    > uv add ${PACKAGE_NAME}
    

    Dev Versions

    Pulumi SDKs also publish pre-release versions that include all the latest changes from the main development branch. If you would like to install a pre-release version, you can use the --pre flag with pip or the --allow-prereleases flag with poetry. For example:

    pip install --pre -r requirements.txt
    poetry add --allow-prereleases ${PACKAGE_NAME}
    

    Package Documentation

    In addition to the standard packages the Pulumi Registry houses 100+ Python packages.

    Standard Packages

    Pulumi SDK
    pulumi
    Pulumi Policy
    pulumi_policy
    Pulumi Terraform
    pulumi_terraform
      Platform Engineering Workshop Series - Register Now