Skip to content

Improve Settings Reference documentation and fix python-env.* naming inconsistency #1114

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
StellaHuang95 wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Improve Settings Reference documentation and fix python-env.* naming inconsistency #1114

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9d34de4
update settings in readme
StellaHuang95 Jan 22, 2026
529cf30
fix test failure
StellaHuang95 Jan 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 27 additions & 7 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -125,13 +125,33 @@ All commands can be accessed via the Command Palette (`ctrl/cmd + Shift + P`):

## Settings Reference

| Setting (python-envs.) | Default | Description |
| --------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| defaultEnvManager | `"ms-python.python:venv"` | The default environment manager used for creating and managing environments. |
| defaultPackageManager | `"ms-python.python:pip"` | The default package manager to use for installing and managing packages. This is often dictated by the default environment manager but can be customized. |
| pythonProjects | `[]` | A list of Python workspaces, specified by the path, in which you can set particular environment and package managers. You can set information for a workspace as `[{"path": "/path/to/workspace", "envManager": "ms-python.python:venv", "packageManager": "ms-python.python:pip"]}`. |
| terminal.showActivateButton | `false` | (experimental) Show a button in the terminal to activate/deactivate the current environment for the terminal. This button is only shown if the active terminal is associated with a project that has an activatable environment. |
| python-envs.terminal.autoActivationType | `command` | Specifies how the extension can activate an environment in a terminal. Utilizing Shell Startup requires changes to the shell script file and is only enabled for the following shells: zsh, fsh, pwsh, bash, cmd. When set to `command`, any shell can be activated. This setting applies only when terminals are created, so you will need to restart your terminals for it to take effect. To revert changes made during shellStartup, run `Python Envs: Revert Shell Startup Script Changes`. |
### Python Environments Settings (`python-envs.`)

| Setting (python-envs.) | Default | Description |
| ---------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| defaultEnvManager | `"ms-python.python:venv"` | The default environment manager used for creating and managing environments. |
| defaultPackageManager | `"ms-python.python:pip"` | The default package manager to use for installing and managing packages. This is often dictated by the default environment manager but can be customized. |
| pythonProjects | `[]` | A list of Python workspaces, specified by the path, in which you can set particular environment and package managers. You can set information for a workspace as `[{"path": "/path/to/workspace", "envManager": "ms-python.python:venv", "packageManager": "ms-python.python:pip"]}`. |
| terminal.showActivateButton | `false` | (experimental) Show a button in the terminal to activate/deactivate the current environment for the terminal. This button is only shown if the active terminal is associated with a project that has an activatable environment. |
| terminal.autoActivationType | `"command"` | Specifies how the extension can activate an environment in a terminal. Accepted values: `command` (execute activation command in terminal), `shellStartup` (modify shell startup scripts), `off` (no auto-activation). Shell startup is only supported for: zsh, fish, pwsh, bash, cmd. **Takes precedence over** `python.terminal.activateEnvironment`. Restart terminals after changing this setting. To revert shell startup changes, run `Python Envs: Revert Shell Startup Script Changes`. |
| alwaysUseUv | `true` | When `true`, [uv](https://github.com/astral-sh/uv) will be used to manage all virtual environments if available. When `false`, uv will only manage virtual environments explicitly created by uv. |
| globalSearchPaths | `[]` | Global search paths for Python environments. Array of absolute directory paths to search for environments at the user level. This setting is merged with the legacy `python.venvPath` and `python.venvFolders` settings. |
| workspaceSearchPaths | `[]` | Workspace search paths for Python environments. Can be absolute paths or relative directory paths searched within the workspace. |

### Supported Legacy Python Settings (`python.`)

The following settings from the Python extension (`python.*`) are also supported by Python Environments.

| Setting (`python.`) | Default | Description |
| ------------------------------ | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| condaPath | `""` | Path to the conda executable. Used to locate and run conda for environment discovery and management. |
| defaultInterpreterPath | `"python"` | Path to the default Python interpreter. |
| envFile | `"${workspaceFolder}/.env"` | Path to the environment file (`.env`) containing environment variable definitions. Used with `python.terminal.useEnvFile` to inject environment variables into terminals. |
| terminal.activateEnvironment | `true` | Legacy setting for terminal auto-activation. If `python-envs.terminal.autoActivationType` is not set and this is `false`, terminal auto-activation will be disabled. **Superseded by** `python-envs.terminal.autoActivationType` which takes precedence when configured. |
| terminal.executeInFileDir | `false` | When `true`, the terminal's working directory will be set to the directory containing the Python file being executed, rather than the project root directory. |
| terminal.useEnvFile | `false` | Controls whether environment variables from `.env` files (specified by `python.envFile`) are injected into terminals. |
| venvFolders | `[]` | Array of folder names to search for virtual environments. These folders are searched in addition to the standard locations. **Note:** This setting is merged with `python-envs.globalSearchPaths`. Consider migrating to `python-envs.globalSearchPaths` for future compatibility. |
| venvPath | `""` | Path to a folder containing virtual environments. **Note:** This setting is merged with `python-envs.globalSearchPaths`. Consider migrating to `python-envs.globalSearchPaths` for future compatibility. |

## Extensibility

Expand Down
8 changes: 4 additions & 4 deletions package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -111,18 +111,18 @@
"default": false,
"scope": "resource"
},
"python-env.globalSearchPaths": {
"python-envs.globalSearchPaths": {
"type": "array",
"markdownDescription": "%python-env.globalSearchPaths.description%",
"markdownDescription": "%python-envs.globalSearchPaths.description%",
"default": [],
"scope": "machine",
"items": {
"type": "string"
}
},
"python-env.workspaceSearchPaths": {
"python-envs.workspaceSearchPaths": {
"type": "array",
"description": "%python-env.workspaceSearchPaths.description%",
"description": "%python-envs.workspaceSearchPaths.description%",
"default": [],
"scope": "resource",
"items": {
Expand Down
4 changes: 2 additions & 2 deletions package.nls.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,8 @@
"python-envs.terminal.autoActivationType.shellStartup": "Activation by modifying the terminal shell startup script. To use this feature we will need to modify your shell startup scripts.",
"python-envs.terminal.autoActivationType.off": "No automatic activation of environments.",
"python-envs.terminal.useEnvFile.description": "Controls whether environment variables from .env files and python.envFile setting are injected into terminals.",
"python-env.globalSearchPaths.description": "Global search paths for Python environments. Absolute directory paths that are searched at the user level.\n\n**Legacy Setting Support:** This setting is merged with the legacy `python.venvPath` and `python.venvFolders` settings. All paths from these three settings are combined into a single list of search paths. The legacy settings `python.venvPath` and `python.venvFolders` will be deprecated in the future, after which this setting will fully replace them. Please consider migrating your paths to this setting.",
"python-env.workspaceSearchPaths.description": "Workspace search paths for Python environments. Can be absolute paths or relative directory paths searched within the workspace.",
"python-envs.globalSearchPaths.description": "Global search paths for Python environments. Absolute directory paths that are searched at the user level.\n\n**Legacy Setting Support:** This setting is merged with the legacy `python.venvPath` and `python.venvFolders` settings. All paths from these three settings are combined into a single list of search paths. The legacy settings `python.venvPath` and `python.venvFolders` will be deprecated in the future, after which this setting will fully replace them. Please consider migrating your paths to this setting.",
"python-envs.workspaceSearchPaths.description": "Workspace search paths for Python environments. Can be absolute paths or relative directory paths searched within the workspace.",
"python-envs.terminal.revertStartupScriptChanges.title": "Revert Shell Startup Script Changes",
"python-envs.reportIssue.title": "Report Issue",
"python-envs.setEnvManager.title": "Set Environment Manager",
Expand Down
6 changes: 3 additions & 3 deletions src/managers/common/nativePythonFinder.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -455,7 +455,7 @@ export async function getAllExtraSearchPaths(): Promise<string[]> {
*/
function getGlobalSearchPaths(): string[] {
try {
const envConfig = getConfiguration('python-env');
const envConfig = getConfiguration('python-envs');
const inspection = envConfig.inspect<string[]>('globalSearchPaths');

const globalPaths = inspection?.globalValue || [];
Expand All @@ -471,12 +471,12 @@ function getGlobalSearchPaths(): string[] {
*/
function getWorkspaceSearchPaths(): string[] {
try {
const envConfig = getConfiguration('python-env');
const envConfig = getConfiguration('python-envs');
const inspection = envConfig.inspect<string[]>('workspaceSearchPaths');

if (inspection?.globalValue) {
traceError(
'Error: python-env.workspaceSearchPaths is set at the user/global level, but this setting can only be set at the workspace or workspace folder level.',
'Error: python-envs.workspaceSearchPaths is set at the user/global level, but this setting can only be set at the workspace or workspace folder level.',
);
}

Expand Down
2 changes: 1 addition & 1 deletion src/test/managers/common/nativePythonFinder.getAllExtraSearchPaths.unit.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@ suite('getAllExtraSearchPaths Integration Tests', () => {
if (section === 'python') {
return pythonConfig;
}
if (section === 'python-env') {
if (section === 'python-envs') {
return envConfig;
}
throw new Error(`Unexpected configuration section: ${section}`);
Expand Down