From 4cbb23030bcab7d0ddc31a28d8f53e1cb4c1902d Mon Sep 17 00:00:00 2001 From: eleanorjboyd <26030610+eleanorjboyd@users.noreply.github.com> Date: Wed, 7 May 2025 10:05:24 -0700 Subject: [PATCH 1/4] design doc addition --- docs/design.md | 130 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 130 insertions(+) create mode 100644 docs/design.md diff --git a/docs/design.md b/docs/design.md new file mode 100644 index 00000000..56e9f85e --- /dev/null +++ b/docs/design.md @@ -0,0 +1,130 @@ + +# Python Environments API +The following helps describe the technical design of the Python Environments Extension for use mainly by contributing extension authors. This extension is the entry point which will surface the entire environment management experience for Python in VS Code and its modularity should allow for individual tools / libraries to implement these methods for their tool making them usable in VS Code. + + +**Table of Contents** +- [Python Environments API](#python-environments-api) + - [Functionalities of Extension \& its API](#functionalities-of-extension--its-api) + - [API Surface](#api-surface) + - [Objects in Extension API](#objects-in-extension-api) + - [Relationships between API Components](#relationships-between-api-components) + - [Workspace and Environments](#workspace-and-environments) + - [EnvironmentManagers and PackageManagers](#environmentmanagers-and-packagemanagers) + - [Packages and Related Objects](#packages-and-related-objects) + - [PythonProject and PythonProjectCreator](#pythonproject-and-pythonprojectcreator) + - [Connection to UI](#connection-to-ui) + - [Python Side Pane](#python-side-pane) + - [Copilot Tooling](#copilot-tooling) + - [Command Palette](#command-palette) + - [Contributions to File Explorer](#contributions-to-file-explorer) + + +## Functionalities of Extension & its API +The python environment extension has four main functionalities: +- getting / setting environments (including the packages found in them) +- terminal activation +- code execution +- project management + +## API Surface +- **PythonProjectApi** -> The API for interacting with Python projects. +- **PythonExecutionApi** +- **PythonEnvironmentApi** -> The API for interacting with Python environments, package +- **PythonEnvironmentManagerApi** +- **PythonPackageManagerApi** + + +## Objects in Extension API +The core components are as follows: +- `PythonEnvironment`: a python environment + - Has unique id and correlates to a `EnvironmentManager` + - Contains `PythonEnvironmentExecutionInfo` +- `EnvironmentManager`: an object which manages `PythonEnvironment` + - registered by an extension in form with id `.:` + - acts on an environment (get, set, etc) `PythonEnvironment` + - one `EnvironmentManager` can create many `PythonEnvironment` objects +- `PackageManagementOptions`: actions relating to, and specifying packages +- `PackageManager`: an object which manages packages + - registered by an extension in form with id `.:` + - performs actions for packages using `PackageManagementOptions` + + +## Relationships between API Components +Generally in the extension, the PackageManagers and EnvironmentManagers handle the entry-point for contributing actions in the area of getting and setting environments as well as accessing activation / execution events. Projects can be created via PythonProjectCreators but ongoing management of projects in a workspace are handled through the envs ext API. + + +### Workspace and Environments +The relationship between **workspaces** and **environments** in the extension can be any of the following configurations: +| workspace | environment | description | example | +| -------- | ------- | -------- | ------- | +| 1 | 1 | single workspace, single environment | simplest, think Django app in a workspace | +| 1 | n | single workspace, multiple environments | one workspace with a client and server which have diff envs OR monorepo with multiple environments | +| m | n | multiroot workspace, multiple environments | many workspaces with many environments | +| m | 1 | multiroot workspace, single environment | covered in m:n scenario | + + + `PythonEnvironment` describes a unique python environment that is identified by its `PythonEnvironmentId` a property containing the `id` of the environment and the `managerId`. A `PythonEnvironment` object can contain many attributes included in the code block below. Note `execInfo` of type `PythonEnvironmentExecutionInfo` contains information on both terminal activation for a given environment and code execution. The group attribute can be used to provide differentiation between environments from the same manager, such as named vs unnamed conda environments. + +``` +PythonEnvironment +- envId: PythonEnvironmentId; (unique identifier) + - id: string; + - managerId: string; +- name: string; +- displayName: string; +- displayPath: string; +- version: string; +- environmentPath: Uri; +- execInfo: PythonEnvironmentExecutionInfo; +- sysPrefix: string; +- optional: shortDisplayName?, description?, tooltip?, iconPath?, group? +``` + +### EnvironmentManagers and PackageManagers +The API surfaces the concept of managers which can be registered by external contributors / extensions and provide a variety of actions. These managers can usually be referenced under their nested ownership notation: `.:` + +An `EnvironmentManager` can provide a variety of actions for environments under its management such as create, remove, set, get, etc. The default `EnvironmentManager` defined in this extension is `venv`. + +A `PackageManager` provides a variety of action which can be taken on an environment with that environment provided as an argument. An `EnvironmentManager` when registered is required to provide a `preferredPackageManagerId` attribute meaning each `EnvironmentManager` will have one `PackageManager` but the reverse is not true (a `PackageManager` can work with many `EnvironmentManager`). Once set on registration, this relationship cannot be amended unless a new `EnvironmentManager` is created. Example `EnvironmentManager-PackageManager` relationships include: + +| EnvironmentManager | PackageManager | +| -------- | ------- | +| venv | pip | +| conda | conda | + + +Note two things in the table, a given python tool like conda can be both a `EnvironmentManager` and a `PackageManager`. Secondly an `EnvironmentManager`'s preferred `PackageManager` is an opinionated selection made by the manager's author but can be overruled in specific package actions (ie install packageA using into envA using packageManager X). For the default `EnvironmentManager` (venv) the default `PackageManager` is `pip`. + + +Connecting these objects back to the API functionality, the `EnvironmentManager` is the essential object in "terminal activation" and "code execution" with each of these actions tied to a specific environment. Meanwhile the packageManager is used in tandem with the environment manager to handle "getting / setting environments" as this action includes the packages found in them. + + +### Packages and Related Objects +Instances of packages are uniquely referenced by PackageId which is made up of 3 attributes, string id of the package, managerId and environmentId. The string Id of a package is the same name registered with pip. PackageInfo, which the package interface extends, contains information on the package like description and version. Package in this extension follows the same definition as that used for python overall, that package is an installable piece of code. This means that any packages, regardless of if they are on PyPi or instantiated as part of the top 1000 pkgs in the extension, can be created and used in the extension. + +As an example of the `package` design, if there was a workspace with two environments which both had the same version of `pytest` installed, their Package instances would be unique, separated by the environmentId attribute, but their packageInfo may be the same or different. A difference could arise if each environment had a different `pytest` version, since version is stored in `packageInfo`. + +By default, the top 1000 packages per pypi statistics are instantiated in the environments extension. When it comes time to install a package, the package id (a string) is the value that will be passed to the install helper. Anything thats installable / modular python code can be a package in this extension. + +### PythonProject and PythonProjectCreator +Finally there is the concept of a `PythonProject` which for the purposes of this extension, we will define as "a single or group of python files which have a environment connected to them".`PythonProject` do not have a Manager but instead the `PythonProjectCreator` since creation is the only action to take on a `PythonProject` object. Once created the project, the association between the files and the environment will be maintained but otherwise the project can be edited using normal file-system operations. `PythonProject` objects can look many different ways; a few options of things that could be a `PythonProject` are: a python package, a server, a Django web app, a single script with the PEP723, etc. + +A `PythonProjectCreator` is contributed by an extensions and provides a `create` function that will return a `PythonProject`. The `supportsQuickCreate` just defines if this project creation step can be done without any user input- ie there is a default way to create a project of this type. All projects in a workspace can be managed (add, remove, get) via the PythonProject specific APIs (PythonProjectGetterApi, PythonProjectModifyApi). + + +## Connection to UI + +Users of the Python Environments extension can interact with the environments extension in a few different ways. These entry points include the "Python Side Pane", contributed commands to VS Code menus / command palette, and actions taken by copilot. + +### Python Side Pane + +Selectable by the Python logo icon and located by default in the sidepane, the Python Side Pane is the main surface of information a user sees about their python environments. The user can take actions from the UI, such as "install packages" or just view existing information like projects in a workspace. + + +### Copilot Tooling +xxxx + +### Command Palette + +### Contributions to File Explorer From bd8db4ff7b163f86059f4c010ebe33163056dad4 Mon Sep 17 00:00:00 2001 From: Eleanor Boyd <26030610+eleanorjboyd@users.noreply.github.com> Date: Mon, 2 Feb 2026 11:47:40 -0800 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: Courtney Webster <60238438+cwebster-99@users.noreply.github.com> Co-authored-by: Karthik Nadig --- docs/design.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/design.md b/docs/design.md index 56e9f85e..89b860ef 100644 --- a/docs/design.md +++ b/docs/design.md @@ -1,6 +1,6 @@ # Python Environments API -The following helps describe the technical design of the Python Environments Extension for use mainly by contributing extension authors. This extension is the entry point which will surface the entire environment management experience for Python in VS Code and its modularity should allow for individual tools / libraries to implement these methods for their tool making them usable in VS Code. +The following guide describes the technical design of the Python Environments Extension. Its intended use is mainly for contributing extension authors. This extension is the entry point which will surface the entire environment management experience for Python in VS Code and its modularity should allow for individual tools / libraries to implement these methods for their tool making them usable in VS Code. **Table of Contents** @@ -21,7 +21,7 @@ The following helps describe the technical design of the Python Environments Ext ## Functionalities of Extension & its API -The python environment extension has four main functionalities: +The Python Environments extension has four main functionalities: - getting / setting environments (including the packages found in them) - terminal activation - code execution @@ -37,16 +37,16 @@ The python environment extension has four main functionalities: ## Objects in Extension API The core components are as follows: -- `PythonEnvironment`: a python environment +- `PythonEnvironment`: a python environment (created using `createPythonEnvironmentItem`) - Has unique id and correlates to a `EnvironmentManager` - Contains `PythonEnvironmentExecutionInfo` - `EnvironmentManager`: an object which manages `PythonEnvironment` - - registered by an extension in form with id `.:` + - registered by an extension in form with id `.:` (id is generated internally by extension) - acts on an environment (get, set, etc) `PythonEnvironment` - one `EnvironmentManager` can create many `PythonEnvironment` objects - `PackageManagementOptions`: actions relating to, and specifying packages - `PackageManager`: an object which manages packages - - registered by an extension in form with id `.:` + - registered by an extension in form with id `.:` (Id is generated internally by the extension) - performs actions for packages using `PackageManagementOptions` @@ -56,7 +56,7 @@ Generally in the extension, the PackageManagers and EnvironmentManagers handle t ### Workspace and Environments The relationship between **workspaces** and **environments** in the extension can be any of the following configurations: -| workspace | environment | description | example | +| Workspace | Environment | Description | Example | | -------- | ------- | -------- | ------- | | 1 | 1 | single workspace, single environment | simplest, think Django app in a workspace | | 1 | n | single workspace, multiple environments | one workspace with a client and server which have diff envs OR monorepo with multiple environments | @@ -90,8 +90,10 @@ A `PackageManager` provides a variety of action which can be taken on an environ | EnvironmentManager | PackageManager | | -------- | ------- | -| venv | pip | +| venv | pip/uv | | conda | conda | +| pyenv | pip/uv | +| poetry | poetry | Note two things in the table, a given python tool like conda can be both a `EnvironmentManager` and a `PackageManager`. Secondly an `EnvironmentManager`'s preferred `PackageManager` is an opinionated selection made by the manager's author but can be overruled in specific package actions (ie install packageA using into envA using packageManager X). For the default `EnvironmentManager` (venv) the default `PackageManager` is `pip`. From b44a3ce7fcb70220f324ba28969b3f59b1f7be59 Mon Sep 17 00:00:00 2001 From: Eleanor Boyd <26030610+eleanorjboyd@users.noreply.github.com> Date: Mon, 2 Feb 2026 12:09:41 -0800 Subject: [PATCH 3/4] Address PR review comments: add PythonExecutionApi description, note envId is autogenerated/immutable, and fill in Copilot Tooling section --- docs/design.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/docs/design.md b/docs/design.md index 89b860ef..ba6de449 100644 --- a/docs/design.md +++ b/docs/design.md @@ -1,4 +1,3 @@ - # Python Environments API The following guide describes the technical design of the Python Environments Extension. Its intended use is mainly for contributing extension authors. This extension is the entry point which will surface the entire environment management experience for Python in VS Code and its modularity should allow for individual tools / libraries to implement these methods for their tool making them usable in VS Code. @@ -29,7 +28,7 @@ The Python Environments extension has four main functionalities: ## API Surface - **PythonProjectApi** -> The API for interacting with Python projects. -- **PythonExecutionApi** +- **PythonExecutionApi** -> The API for running code (experimental) - **PythonEnvironmentApi** -> The API for interacting with Python environments, package - **PythonEnvironmentManagerApi** - **PythonPackageManagerApi** @@ -64,11 +63,11 @@ The relationship between **workspaces** and **environments** in the extension ca | m | 1 | multiroot workspace, single environment | covered in m:n scenario | - `PythonEnvironment` describes a unique python environment that is identified by its `PythonEnvironmentId` a property containing the `id` of the environment and the `managerId`. A `PythonEnvironment` object can contain many attributes included in the code block below. Note `execInfo` of type `PythonEnvironmentExecutionInfo` contains information on both terminal activation for a given environment and code execution. The group attribute can be used to provide differentiation between environments from the same manager, such as named vs unnamed conda environments. + `PythonEnvironment` describes a unique python environment that is identified by its `PythonEnvironmentId` a property containing the `id` of the environment and the `managerId`. The `envId` is autogenerated and immutable. A `PythonEnvironment` object can contain many attributes included in the code block below. Note `execInfo` of type `PythonEnvironmentExecutionInfo` contains information on both terminal activation for a given environment and code execution. The group attribute can be used to provide differentiation between environments from the same manager, such as named vs unnamed conda environments. ``` PythonEnvironment -- envId: PythonEnvironmentId; (unique identifier) +- envId: PythonEnvironmentId; (unique identifier, autogenerated and immutable) - id: string; - managerId: string; - name: string; @@ -125,7 +124,13 @@ Selectable by the Python logo icon and located by default in the sidepane, the P ### Copilot Tooling -xxxx +The extension contributes language model tools that enable GitHub Copilot to interact with Python environments. These tools allow Copilot to: +- Query and list available Python environments +- Get information about the currently selected environment +- Install and manage packages in environments +- Create new environments and projects + +This integration allows users to manage their Python environments through natural language conversations with Copilot in VS Code. ### Command Palette From e086ac139c25bcf50da262f4b39f91829e82a02a Mon Sep 17 00:00:00 2001 From: eleanorjboyd <26030610+eleanorjboyd@users.noreply.github.com> Date: Mon, 2 Feb 2026 12:10:16 -0800 Subject: [PATCH 4/4] updates --- docs/managing-python-projects.md | 387 +++++++++++++++++++++++++++++++ 1 file changed, 387 insertions(+) create mode 100644 docs/managing-python-projects.md diff --git a/docs/managing-python-projects.md b/docs/managing-python-projects.md new file mode 100644 index 00000000..9b4380a1 --- /dev/null +++ b/docs/managing-python-projects.md @@ -0,0 +1,387 @@ +# Making and Managing Python Projects + +This guide explains how to set up and manage Python projects in VS Code using the Python Environments extension. By the end, you'll understand what a "project" is, how to create and configure them, and how to assign the right environments and package managers to each one. + +## What is a Python Project? + +A **Python Project** is any file or folder that contains runnable Python code and needs its own environment. Think of it as a way to tell VS Code: "This folder (or file) is a distinct Python codebase that should use a specific Python interpreter and package manager." + +By default, every workspace folder you open in VS Code is automatically treated as a project. However, you can also: + +- Add subfolders as separate projects (useful for mono-repos) +- Add individual Python files as projects (great for standalone scripts) +- Create brand new projects from templates + +### Why use projects? + +Projects solve a common challenge: **different parts of your workspace need different Python environments**. + +| Scenario | Without Projects | With Projects | +|----------|-----------------|---------------| +| Mono-repo with multiple services | All services share one environment | Each service gets its own environment | +| Testing different Python versions | Manual interpreter switching | Assign Python 3.10 to one folder, 3.12 to another | +| Shared workspace with scripts and packages | Confusing environment management | Clear separation of concerns | + +## The Python Environments Panel + +The Python Environments extension adds a dedicated view to VS Code's Activity Bar. This panel has two main sections: + +1. **Python Projects**: Shows all projects in your workspace and their selected environments +2. **Environment Managers**: Shows available environment managers (venv, conda, etc.) with their environments + + + +## Adding Projects to Your Workspace + +There are several ways to add Python projects: + +### Method 1: Add existing files or folders + +Use this when you have existing Python code that should be treated as a separate project. + +1. Open the Python Environments panel in the Activity Bar. +2. In the **Python Projects** section, click the **+** button. +3. Select **Add Existing**. +4. Browse to and select the folder(s) or file(s) you want to add. +5. Select **Open** to add them as projects. + +Alternatively, right-click any folder or Python file in the Explorer and select **Add as Python Project**. + + + +### Method 2: Auto-find projects + +Use this to quickly discover all Python projects in your workspace based on common project markers. + +1. Open the Python Environments panel. +2. Click the **+** button in the Python Projects section. +3. Select **Auto Find**. +4. The extension searches for folders containing `pyproject.toml` or `setup.py` files. +5. Select which discovered projects to add from the list. + +> **Tip**: Auto-find is especially useful when you clone a mono-repo and want to quickly identify all its Python projects. + +### Method 3: Create a new project from a template + +Use this to scaffold a brand new Python project with the correct structure and files. + +1. Open the Command Palette (`Cmd+Shift+P` on macOS, `Ctrl+Shift+P` on Windows/Linux). +2. Run **Python Envs: Create New Project from Template**. +3. Choose a template type: + - **Package**: A structured Python package with `pyproject.toml`, tests folder, and package directory + - **Script**: A simple standalone Python file using PEP 723 inline metadata +4. Enter a name for your project. +5. Choose whether to create a virtual environment. + +The extension creates the project structure, adds it to your workspace, and optionally creates a virtual environment. + +#### Package template structure + +When you create a package named `my_package`, the extension generates: + +``` +my_package_project/ +├── pyproject.toml # Project metadata and dependencies +├── dev-requirements.txt # Development dependencies +├── my_package/ # Your package source code +│ └── __init__.py +└── tests/ # Test directory + └── __init__.py +``` + +#### Script template + +When you create a script, the extension generates a single `.py` file with PEP 723 inline script metadata, which allows you to specify dependencies directly in the file. + +## Assigning Environments to Projects + +Each project can have its own Python environment. This is the core benefit of project management. + +### Set an environment for a project + +1. In the **Python Projects** section, find your project. +2. Click on the environment path shown beneath the project name (or "No environment" if none is set). +3. Select an environment from the list of available environments. + +You can also: + +- Click the environment icon next to a project +- Right-click the project and select **Set Project Environment** + + + +### Use an environment from the Environment Managers section + +1. In the **Environment Managers** section, expand a manager (e.g., venv, conda). +2. Find the environment you want to use. +3. Right-click it and select **Set As Project Environment**. +4. Choose which project should use this environment. + +## Setting Environment and Package Managers + +Beyond selecting which Python interpreter a project uses, you can also specify which **environment manager** and **package manager** the project should use. This affects how environments are created and how packages are installed. + +### Environment managers + +Environment managers control how Python environments are created and discovered: + +| Manager | Description | +|---------|-------------| +| `venv` | Built-in Python virtual environments (default) | +| `conda` | Conda environments from Anaconda or Miniconda | +| `pyenv` | Multiple Python versions via pyenv | +| `poetry` | Poetry-managed environments | +| `pipenv` | Pipenv-managed environments | +| `system` | System-installed Python interpreters | + +### Package managers + +Package managers control how packages are installed in environments: + +| Manager | Description | +|---------|-------------| +| `pip` | Standard Python package installer (default) | +| `conda` | Conda package manager for conda environments | + +### Set managers for a project + +1. Right-click a project in the Python Projects section. +2. Select **Set Environment Manager** to change how environments are created. +3. Select **Set Package Manager** to change how packages are installed. + +> **Note**: The default package manager is typically determined by the environment manager. For example, venv environments use pip by default, while conda environments use the conda package manager. + +## Where Settings Are Stored + +The extension stores project configurations in your VS Code settings. Understanding this helps you manage settings across different scopes. + +### Settings location + +Project settings are stored in the `python-envs.pythonProjects` setting. Depending on your workspace setup: + +| Workspace Type | Settings Location | +|----------------|-------------------| +| Single folder | `.vscode/settings.json` in your workspace | +| Multi-root workspace | `.code-workspace` file | + +### Settings structure + +The `pythonProjects` setting is an array of project configurations: + +```json +{ + "python-envs.pythonProjects": [ + { + "path": "backend", + "envManager": "ms-python.python:venv", + "packageManager": "ms-python.python:pip" + }, + { + "path": "ml-service", + "envManager": "ms-python.python:conda", + "packageManager": "ms-python.python:conda" + } + ] +} +``` + +Each project entry contains: + +| Property | Description | +|----------|-------------| +| `path` | Relative path from workspace root to the project | +| `envManager` | ID of the environment manager (e.g., `ms-python.python:venv`) | +| `packageManager` | ID of the package manager (e.g., `ms-python.python:pip`) | +| `workspace` | (Multi-root only) Name of the workspace folder containing the project | + +### Default managers + +You can set default managers that apply to all projects without explicit overrides: + +```json +{ + "python-envs.defaultEnvManager": "ms-python.python:venv", + "python-envs.defaultPackageManager": "ms-python.python:pip" +} +``` + +## Working with Multi-Root Workspaces + +Multi-root workspaces contain multiple top-level folders. The extension handles these seamlessly: + +1. Each workspace folder is automatically treated as a project. +2. You can add sub-projects within any workspace folder. +3. Project settings include a `workspace` property to identify which folder they belong to. +4. When creating a new project from a template, you're prompted to select which workspace folder to use. + +### Example: Multi-root mono-repo + +``` +my-workspace.code-workspace +├── frontend/ → Project with Python 3.12 +│ └── scripts/ → Sub-project with same environment +├── backend/ → Project with Python 3.10, venv +│ ├── api/ → Sub-project with its own venv +│ └── workers/ → Sub-project with its own venv +└── ml-pipeline/ → Project with conda environment +``` + +## Removing Projects + +To remove a project (this does not delete any files): + +1. Right-click the project in the Python Projects section. +2. Select **Remove Python Project**. + +The project is removed from the extension's tracking. Its files remain untouched, and you can always add it back later. + +## Quick Reference: Commands + +Access these via the Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`): + +| Command | Description | +|---------|-------------| +| **Python Envs: Create New Project from Template** | Create a new package or script from a template | +| **Python Envs: Add Python Project** | Add existing files/folders as projects | +| **Python Envs: Set Project Environment** | Change the Python interpreter for a project | +| **Python Envs: Set Environment Manager** | Change how environments are created | +| **Python Envs: Set Package Manager** | Change how packages are installed | +| **Python Envs: Create Environment** | Create a new environment for a project | +| **Python Envs: Manage Packages** | Install or uninstall packages | + +## Quick Reference: Settings + +| Setting | Default | Description | +|---------|---------|-------------| +| `python-envs.defaultEnvManager` | `"ms-python.python:venv"` | Default environment manager for new projects | +| `python-envs.defaultPackageManager` | `"ms-python.python:pip"` | Default package manager for new projects | +| `python-envs.pythonProjects` | `[]` | List of project configurations | + +## Common Scenarios + +### Scenario 1: Mono-repo with microservices + +You have a repository with multiple Python services, each needing isolated dependencies. + +1. Open the root folder in VS Code. +2. Click **+** in Python Projects and select **Auto Find** to discover all services with `pyproject.toml`. +3. Select the services you want to track. +4. For each service, create a virtual environment by right-clicking and selecting **Create Environment**. +5. Each service now runs with its own isolated environment. + +### Scenario 2: Switching a project from venv to conda + +Your data science project needs packages that install more reliably with conda. + +1. Right-click the project in Python Projects. +2. Select **Set Environment Manager** → **conda**. +3. Select **Set Package Manager** → **conda**. +4. Right-click the project again and select **Create Environment** to create a new conda environment. + +### Scenario 3: Adding a standalone script + +You have a utility script that needs specific packages without affecting your main project. + +1. Right-click the `.py` file in Explorer. +2. Select **Add as Python Project**. +3. The script is now a separate project that can have its own environment. + +## Troubleshooting + +### Project not appearing in the panel + +- Verify the file or folder is inside your workspace +- Check if it was already added (duplicates are prevented) +- Try using **Add Existing** and manually selecting it + +### Environment changes not taking effect + +- Restart any open terminals to use the new environment +- Check that the environment actually exists and is valid +- Verify the `pythonProjects` setting in `.vscode/settings.json` + +### Settings not persisting + +- Ensure you have write access to the workspace folder +- Check if settings are being overridden at a higher scope (User vs. Workspace) +- For multi-root workspaces, verify the `.code-workspace` file is being saved + +## Related Resources + +- [Environment Management](../README.md#environment-management): Learn about creating and managing Python environments +- [Package Management](../README.md#package-management): Learn how to install and manage packages +- [Projects API Reference](projects-api-reference.md): Technical reference for extension authors + + + + +RawEventsVSCodeExt +| where EventName == "ms-python.vscode-python-envs/project_structure" +| extend ProjectCount = toint(Properties["totalprojectcount"]) +| extend Bucket = case( + ProjectCount == 0, "0", + ProjectCount == 1, "1", + ProjectCount == 2, "2", + ProjectCount == 3, "3", + ProjectCount >= 4, "4+", + "unknown") +| summarize Count = count() by Bucket +| order by Bucket asc + +0 4,231 +1 38,743 93.6% +2 1,163 2.8% +3 429 1% +4+ 1,051 2.5% + +1-4 == 41,386 + +RawEventsVSCodeExt +| where EventName == "ms-python.vscode-python-envs/project_structure" +| extend ProjectCount = toint(Properties["uniqueinterpretercount"]) +| extend Bucket = case( + ProjectCount == 0, "0", + ProjectCount == 1, "1", + ProjectCount == 2, "2", + ProjectCount == 3, "3", + ProjectCount >= 4, "4+", + "unknown") +| summarize Count = count() by Bucket +| order by Bucket asc + +0 4,934 10.9% +1 39,054 86.6% +2 820 1.8% +3 138 0.3% +4+ 160 0.35 + +0-4+ = 45,106 + + +RawEventsVSCodeExt +| where EventName == "ms-python.vscode-python-envs/project_structure" +| extend ProjectCount = toint(Properties["projectunderroot"]) +| extend Bucket = case( + ProjectCount == 0, "0", + ProjectCount == 1, "1", + ProjectCount == 2, "2", + ProjectCount == 3, "3", + ProjectCount >= 4, "4+", + "unknown") +| summarize Count = count() by Bucket +| order by Bucket asc + + +0 45,293 98.2% +1 445 1% +2 119 0.25% +3 29 +4+ 194 0.4% + +0-4+: 46,080 \ No newline at end of file