api

@vscode/python-environments

This package provides type declarations and a helper to access the API exposed by the Python Environments extension for VS Code.

Usage

1. Install the package and add an extensionDependencies entry in your extension's package.json:

// package.json
{
    "extensionDependencies": ["ms-python.vscode-python-envs"]
}

2. Install the npm package:

npm install @vscode/python-environments

3. Import and use the API in your extension:

import { PythonEnvironments } from '@vscode/python-environments';

export async function activate() {
    const api = await PythonEnvironments.api();

    // Get all discovered environments
    const envs = await api.getEnvironments('all');
    for (const env of envs) {
        console.log(env.displayName, env.version);
    }
}

Manager capabilities

Capabilities report general manager support without invoking an operation:

import { PackageCapability, PythonEnvironments } from '@vscode/python-environments';

const api = await PythonEnvironments.api();
const environment = await api.getEnvironment(undefined);
if (environment) {
    const support = await api.getPackageManagerCapability(environment, PackageCapability.ListDirect);
    if (support.supported) {
        // Best-effort direct/transitive package classification is available.
    }
}

Manager advertisements are optional for legacy compatibility. Missing maps use method-presence inference and return isLegacy: true; missing keys in a supplied map report unsupported. Support is advisory, not a guarantee that an operation succeeds.

See the capability guide for the full catalog and provider authoring.

Full API reference

📘 Python Environments API reference

The complete manual documents every method and data type, organized by domain - environments, packages, projects, execution, environment variables, and extensibility - with field tables, parameter tables, return types, and examples.

• Environments - discover, resolve, select, create, and remove interpreters
• Packages - list, install, uninstall, and look up versions
• Projects - the folders the extension tracks
• Execution - run Python in terminals, tasks, and background processes
• Environment variables - resolved variables for a scope
• Extensibility - register your own environment manager, package manager, or project creator

See CHANGELOG.md for API changes between versions.