python-env-unblocker

name	python-env-unblocker
description	Fixes VS Code Python environment issues in new workspaces by locating or creating a .venv, wiring the interpreter in workspace settings, enabling terminal activation, and verifying the result. Use when the user says Python is stuck, Select Interpreter keeps popping up, the terminal won’t activate the environment, or imports fail in a new workspace.

Python Environment Unblocker

Use this skill when a Python workspace opens but the interpreter is not selected, the editor keeps asking for a Python environment, or the terminal is using system Python instead of the project venv.

Root-cause pattern

On Windows, the most common cause is:

• the workspace already has a .venv
• but [workspace]/.vscode/settings.json is missing
• so VS Code repeatedly prompts for interpreter selection and terminal activation is inconsistent

Standard fix workflow

1) Inspect the workspace

Check whether these paths exist:

• .venv/
• .venv/Scripts/python.exe
• .vscode/settings.json

2) If .venv exists but settings are missing

Create [workspace]/.vscode/settings.json with:

{
  "python.defaultInterpreterPath": "${workspaceFolder}\\.venv\\Scripts\\python.exe",
  "python.terminal.activateEnvironment": true,
  "python.analysis.extraPaths": [
    "${workspaceFolder}"
  ]
}

3) If the workspace has no .venv

Prefer uv; fall back to venv:

uv venv .venv

If uv is unavailable:

py -3 -m venv .venv

4) Verify before claiming success

Run the workspace interpreter directly:

.\.venv\Scripts\python.exe -c "import sys; print(sys.executable)"

Only say the issue is fixed after the interpreter path prints from the workspace .venv.

5) If the user wants a system-level fix

Update VS Code user settings to include:

{
  "python.defaultInterpreterPath": "${workspaceFolder}\\.venv\\Scripts\\python.exe",
  "python.terminal.activateEnvironment": true
}

This makes new workspaces prefer a local .venv automatically.

Guardrails

• Preserve existing settings; only add the needed Python keys.
• Do not assume system Python is acceptable when the repo uses .venv.
• On Windows JSON paths must use escaped backslashes.
• Always verify with a fresh command output.

Fast result template

Report back with:

1. root cause found
2. files/settings created or updated
3. verification evidence
4. whether a reload of the VS Code window is recommended