🚨 Pulumi Error: 'unable to find virtual environment; run pulumi install or python -m venv venv' — Cause, Fix, and Troubleshooting Guide

Overview

error: failed to prepare environment: unable to find virtual environment means Pulumi’s Python language host was told (in Pulumi.yaml) to run your program inside a virtual environment, but the directory that virtualenv should live in does not exist. Pulumi will not silently fall back to your global Python; it stops before it ever imports your __main__.py.

This is a setup error, not a code error. It almost always appears right after pulumi new, a fresh git clone, a CI checkout, or after someone deleted the venv/ folder. The fix is to create the environment and install the project’s dependencies.

error: failed to prepare environment: unable to find virtual environment; run 'pulumi install' or 'python -m venv venv'

Symptoms

• pulumi preview, pulumi up, pulumi destroy, or pulumi stack fails immediately, before any resources are shown.
• The error mentions a virtual environment and suggests pulumi install or python -m venv venv.
• The project’s Pulumi.yaml has a runtime block with virtualenv: set.
• There is no venv/ (or whatever the configured name is) directory in the project root, or it is empty/corrupt.
• Works on a teammate’s machine but not on a freshly cloned copy or in a CI runner.

Common Root Causes

1. The virtualenv was never created

pulumi new python (and the AWS/GCP/Azure Python templates) write a Pulumi.yaml that points the runtime at a venv folder, but on some flows the environment is not yet built. A fresh clone never contains venv/ because it is git-ignored.

name: my-infra
runtime:
  name: python
  options:
    virtualenv: venv

That virtualenv: venv line tells Pulumi: “always execute my program using ./venv.” If ./venv is absent, you get the error.

2. The venv folder was deleted or is in the wrong place

venv/ is listed in .gitignore, so it never travels with the repo. Cleaning the workspace, switching machines, or running in a container all leave you without it. The path is resolved relative to the directory containing Pulumi.yaml, so running pulumi from a parent or child directory can also “lose” it.

3. Name mismatch between Pulumi.yaml and the actual folder

If Pulumi.yaml says virtualenv: venv but you created .venv (or env), Pulumi looks in the wrong place and reports the environment missing.

# Pulumi.yaml expects:   ./venv
# You actually created:  ./.venv   <-- mismatch

4. A broken or partial environment

An interrupted python -m venv or a venv whose interpreter was upgraded/removed leaves a directory that exists but has no working python. Pulumi treats it as unusable.

How to Diagnose

Confirm which environment Pulumi expects:

# Show the runtime options, including the virtualenv name
cat Pulumi.yaml

Check whether that folder actually exists and has an interpreter:

# Does the expected venv directory exist?
ls -la venv/bin/python    # macOS/Linux
ls -la venv\Scripts\python.exe   # Windows

Verify your base Python is new enough (Pulumi supports modern CPython; 3.9+ is a safe floor):

python3 --version
which python3

List the declared dependencies so you know what will be installed:

cat requirements.txt

Fixes

The one-command fix (recommended): pulumi install reads Pulumi.yaml, creates the configured virtualenv if it is missing, and installs requirements.txt into it.

# Run from the directory containing Pulumi.yaml
pulumi install

Create the venv manually if you prefer explicit control: Match the folder name in Pulumi.yaml exactly (here, venv).

# 1. Create the virtual environment
python3 -m venv venv

# 2. Activate it
source venv/bin/activate        # macOS/Linux
# venv\Scripts\activate         # Windows PowerShell/CMD

# 3. Install project dependencies into it
pip install -r requirements.txt

After this, venv/bin/python exists and pulumi preview will run. You do not have to keep the venv activated once it is built — because Pulumi.yaml names it, Pulumi activates it automatically for each command.

Fix a name mismatch: Either rename the folder or update Pulumi.yaml so both agree.

runtime:
  name: python
  options:
    virtualenv: .venv   # point at the folder you actually created

Rebuild a corrupted environment: Delete and recreate it cleanly.

rm -rf venv
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

In CI/CD: Add an install step before any Pulumi command. With the Pulumi GitHub Action or a plain runner:

# CI step, run in the project directory
pulumi install        # creates venv + installs requirements
pulumi preview --stack dev

What to Watch Out For

• venv/ is git-ignored on purpose — never commit it. Instead, commit requirements.txt and run pulumi install on each new checkout.
• The virtualenv value in Pulumi.yaml is resolved relative to that file’s directory; always run pulumi from the project root (or use --cwd).
• If you switch Python versions (e.g. upgrade via Homebrew/pyenv), the old venv can break — recreate it.
• Pinning requirements.txt (e.g. pulumi>=3.0,<4.0, pulumi-aws>=6.0,<7.0) keeps CI reproducible and avoids surprise SDK changes.
• If you deliberately want Pulumi to use your ambient Python (not recommended for teams), you can remove the virtualenv option — but then you own dependency management yourself.

Related Guides

• Pulumi Error: ‘invalid configuration key’ — Troubleshooting Guide
• Pulumi Error: ‘resource monitor shut down’ — Troubleshooting Guide
• Pulumi Error: ‘could not load plugin’ — Troubleshooting Guide