🧱 Pulumi Error: 'failed to load language plugin python' Virtualenv/Toolchain Not Found

Exact Error Message

error: failed to load language plugin python: could not read plugin [/home/dev/.pulumi/bin/pulumi-language-python] stdout: EOF
error: could not get plugin info for language "python": could not find plugin for language python

error: an error occurred while advancing the preview: pulumi:providers:pulumi could not
    resolve program: python: no such file or directory

You may also see Error: failed to prepare environment: virtualenv is not present or python not found on path — all are the Python language host failing to start before any resource is even evaluated.

What It Means

Pulumi does not run your Python program directly. The CLI launches a language plugin (pulumi-language-python), which in turn spawns a Python interpreter to execute your __main__.py. When Pulumi cannot find that interpreter, cannot activate the virtual environment declared in Pulumi.yaml, or the language host itself exits early, the plugin fails to load and the operation aborts before touching any provider.

This is an environment problem, not a bug in your infrastructure code. It happens most often after cloning a project onto a fresh machine, in CI runners with no virtualenv, or after upgrading Python and leaving a stale venv pointing at a deleted interpreter.

Common Causes

• The virtualenv folder referenced in Pulumi.yaml (runtime: options: virtualenv: venv) does not exist or was never created.
• python3/python is not on PATH for the shell or CI environment that runs pulumi.
• A stale venv links to a Python version that has been removed or upgraded (broken symlink in venv/bin/python).
• Dependencies were never installed, so the language host cannot import the pulumi package.
• On newer projects, runtime: options: toolchain: poetry (or uv) is set but Poetry/uv is not installed on the machine.

Diagnostic Commands

Confirm which interpreter Pulumi will try to use and whether it exists:

which python3 python
python3 --version

Inspect the runtime options Pulumi reads from the project file:

cat Pulumi.yaml

Look specifically for the runtime block, e.g. runtime: name: python and options: virtualenv: venv.

Check that the referenced virtualenv is real and its interpreter is not a broken symlink:

ls -l venv/bin/python
venv/bin/python -c "import pulumi; print(pulumi.__version__)"

Run Pulumi with verbose logging to see exactly how the language host is invoked and where it dies:

pulumi preview --logtostderr -v=9 2>pulumi.log

Step-by-Step Resolution

1. Read Pulumi.yaml and note the virtualenv (or toolchain) setting. Everything below assumes the common virtualenv: venv.

2. Recreate the virtual environment with a valid interpreter:

python3 -m venv venv

3. Install the project dependencies into that venv so the language host can import pulumi:

venv/bin/python -m pip install --upgrade pip
venv/bin/python -m pip install -r requirements.txt

4. Verify the interpreter can import the SDK — this is exactly what the language host does on startup:

venv/bin/python -c "import pulumi; print('ok', pulumi.__version__)"

5. If you are using a toolchain instead of a raw virtualenv, install and sync it. For Poetry-managed projects:

poetry install

6. Re-run the operation. Pulumi will now find and activate the environment:

pulumi preview

Previewing update (dev)
     Type                 Name          Plan
 +   pulumi:pulumi:Stack  myproj-dev

7. If it still fails in CI, ensure the runner installs Python and creates the venv before pulumi up, because Pulumi will not create it for you unless Pulumi.yaml explicitly sets virtualenv and you run pulumi install.

Prevention

• Commit the runtime: options: virtualenv: venv setting so every machine builds an isolated environment the same way, and never commit the venv/ directory itself.
• Add pulumi install (which creates the venv and installs requirements.txt) as the first step of every CI job.
• Pin your Python version with a .python-version or CI matrix so a host upgrade does not orphan the venv.
• Keep requirements.txt (or pyproject.toml) in sync and include a lower-bound pulumi>= constraint.
• After upgrading system Python, delete and recreate the venv rather than reusing the broken one.

Related Errors

• no resource plugin 'aws' found in the workspace — a missing provider plugin, resolved with pulumi plugin install, not a language-host failure.
• ModuleNotFoundError: No module named 'pulumi_aws' — the venv exists but a specific dependency was not installed.
• failed to load language plugin nodejs — the same class of problem for a TypeScript/JavaScript project.
• error: no stack selected — a stack-selection problem that appears after the language host loads successfully.

Frequently Asked Questions

Does Pulumi create the virtualenv automatically? Only when Pulumi.yaml declares virtualenv and you run pulumi install; otherwise you must create venv and install dependencies yourself before running any command.

Why does it work locally but fail in CI? CI runners usually have no virtualenv and sometimes no python on PATH, so add a step that installs Python and runs pulumi install before pulumi up.

How do I switch a project from a bare interpreter to a managed toolchain? Set runtime: options: toolchain: poetry (or uv) in Pulumi.yaml, then run poetry install so the toolchain owns dependency resolution.

My venv points at a Python that no longer exists — what now? Delete the folder and recreate it with python3 -m venv venv; a broken venv/bin/python symlink is a common cause after upgrading system Python. If you want ready-made prompts to debug and rebuild a broken Pulumi environment, browse the Pulumi prompt library.

Where can I find more fixes like this? See the full Pulumi guides for language-host and provider troubleshooting.