claude-code - 💡(How to fix) Fix [BUG] vscode extension incorrectly prepends /usr/bin to PATH [1 participants]

Preflight Checklist

• I have searched existing issues and this hasn't been reported yet (except once where it was closed as stale)
• This is a single bug report (please file separate reports for different bugs)
• I am using the latest version of Claude Code

What's Wrong?

Summary

When claudeCode.usePythonEnvironment is enabled (the default), the VS Code extension detects the system Python prefix (/usr) as a virtual environment and sets VIRTUAL_ENV=/usr, which prepends /usr/bin to PATH. This changes the PATH ordering for all tool/bash calls within Claude Code sessions.

This happens in projects that have nothing to do with Python and are unaware of this setting, leading to subtle hard-to-diagnose issues which don't reproduce in the user's terminal (or in terminal claude sessions) due to incorrect binary selection (since newer versions are conventionally installed in locations like /usr/local/bin).

Actual behavior

The extension's Python environment activation logic sets:

VIRTUAL_ENV=/usr
PATH=/usr/bin:$PATH

This causes /usr/bin to appear first in PATH, ahead of /usr/local/bin and any other user-configured entries.

Root cause

In extension.js, the usePythonEnvironment feature (enabled by default) calls into Python environment detection. When no virtual environment is found, it falls back to the system Python, whose sys.prefix is /usr. The venv activation logic then does path.join(VIRTUAL_ENV, "bin") → /usr/bin and prepends it to PATH.

This only affects session launches (not the initial auth status call, which uses a different code path).

Impact

• Programs installed in /usr/local/bin may be shadowed by /usr/bin versions
• Breaks user expectations about PATH ordering, especially for users who install newer tool versions to /usr/local/bin
• Does not occur when launching claude from the CLI directly

What Should Happen?

PATH ordering should match the user's login shell. On a typical Ubuntu system with /etc/environment setting PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:..., the user expects /usr/local/bin to come before /usr/bin.

Error Messages/Logs

Steps to Reproduce

1. Open a project in VS Code that has no Python virtual environment (no .venv, no venv, no conda env)
2. System Python's sys.prefix is /usr (standard on Debian/Ubuntu)
3. Start a Claude Code session via the VS Code extension
4. Run echo $PATH in a Claude bash tool call
5. Observe /usr/bin is prepended to PATH

Claude Model

None

Is this a regression?

I don't know

Last Working Version

No response

Claude Code Version

2.1.87 (Claude Code)

Platform

Anthropic API

Operating System

Ubuntu/Debian Linux

Terminal/Shell

Other

Additional Information

Workaround

Add to .vscode/settings.json:

{
    "claudeCode.usePythonEnvironment": false
}

Environment

• Claude Code extension v2.1.87
• VS Code on Linux (Ubuntu)
• No Python virtual environment in project
• System Python at /usr/bin/python3 with sys.prefix = /usr

Refiling #41081, which was closed as stale. The bug still reproduces on the latest version.