Python Interpreter Selection: Quick Reference

How Interpreter Selection Works

When you open a workspace, the Python Environments extension selects an interpreter using this priority order:

Priority	Setting	Scope
1	python-envs.pythonProjects[].envManager	Per-project
2	python-envs.defaultEnvManager	Workspace-wide
3	python.defaultInterpreterPath	Legacy fallback
4	Auto-discovery	Local .venv → global Python

The extension stops at the first match and uses that interpreter.

---

Key Behaviors

Settings Are Only Written When You Act

Opening a workspace never modifies your settings.json. Settings only change when you:

• Manually select an interpreter via the picker
• Create a new environment

User-Configured Settings Beat Defaults

A setting you explicitly configured always wins over a setting with just its default/fallback value—even if that default appears "higher priority."

Example: If you set python.defaultInterpreterPath but never touched defaultEnvManager, your interpreter path is used (not the default venv manager).

Cache Doesn't Override Your Settings

The extension caches resolved environments for performance, but your explicit settings always take precedence over cached values.

---

Common Scenarios

Situation	What Happens
Fresh workspace, no settings	Auto-discovers local .venv or uses system Python
Have python.defaultInterpreterPath set	Uses that interpreter (legacy migration)
Have pythonProjects[] entry for your path	Uses the specified environment manager
Local .venv exists, no settings	Uses the local venv automatically
Multi-root workspace	Each folder resolved independently

---

Settings Reference

// Per-project (highest priority)
"python-envs.pythonProjects": [
  { "path": "./backend", "envManager": "ms-python.python:poetry" }
]

// Workspace default
"python-envs.defaultEnvManager": "ms-python.python:conda"

// Legacy fallback
"python.defaultInterpreterPath": "/usr/local/bin/python3.11"

---

Troubleshooting

If your configured interpreter isn't being used:

1. Check priority order — A higher-priority setting may be overriding yours
2. Verify the path exists — Invalid paths fall through to auto-discovery
3. Check if setting is actually configured — Default/fallback values don't count as "configured"

The extension notifies you when a user-configured setting can't be applied (e.g., manager not registered, path not found).