You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+64-38Lines changed: 64 additions & 38 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,93 +2,119 @@
2
2
3
3
## Overview
4
4
5
-
The Python Environments extension for VS Code helps you manage Python environments and packages using your preferred environment manager backed by its extensible APIs. This extension provides unique support to specify environments for specific files or whole Python folders or projects, including multi-root & mono-repos scenarios.
5
+
The Python Environments extension for VS Code helps you manage Python environments and packages using your preferred environment manager, backed by its extensible APIs. This extension provides unique support for specifying environments for specific files, entire Python folders, or projects, including multi-root and mono-repo scenarios.
6
6
7
-
> Note: This extension is in preview and its APIs and features are subject to change as the project continues to evolve.
7
+
> **Note:** This extension is in preview, and its APIs and features are subject to change as the project evolves.
8
8
9
-
> Important: This extension currently requires the pre-release version of the Python extension (ms-python.python) to operate (version 2024.23.2025010901 or later).
9
+
> **Important:** This extension requires the pre-release version of the Python extension (`ms-python.python`) to operate (version 2024.23.2025010901 or later).
This extension provides an Environments view, which can be accessed via the VS Code Activity Bar, where you can manage your Python environments. Here, you can create, delete, and switch between environments, as well as install and uninstall packages within the selected environment. It also provides APIs for extension developers to contribute their own environment managers.
17
+
This extension provides an Environment Managers view, accessible via the VS Code Activity Bar, where you can:
18
+
19
+
- Create, delete, and switch between environments.
20
+
- Install and uninstall packages within the selected environment.
21
+
- Use APIs to allow extension developers to contribute their own environment managers.
22
+
23
+
![ADD A QUICK REFERENCE FOR UI BUTTON]()
24
+
25
+
To simplify the environment creation process, you can use "Quick Create" to automatically create a new virtual environment using:
19
26
20
-
ADD A QUICK REFERENCE FOR UI BUTTON
27
+
- Your default environment manager (e.g., `venv`)
28
+
- The latest Python version
29
+
- Workspace dependencies
21
30
22
-
To further simplify the environment creation process, you can create a virtual environments using "Quick Create", which uses your default environment manager (i.e. `venv`) and the most updated Python version to create a virtual environment. If you would like more control over your environment features, such as the Python version used, the environment name, packages installed, etc. you can create a custom environment.
31
+
For more control, you can create a custom environment where you can specify Python version, environment name, packages to be installed, and more!
32
+
33
+
![Gif showing environment creation using Quick Create.]()
23
34
24
35
The following environment managers are supported out of the box:
| ms-python.python:venv|`venv`| The default environment manager. It is a built-in environment manager provided by the Python standard library. |
29
40
| ms-python.python:system| System Installed Python | These are global Python installs on your system. These are typically installed with your OS, from [python.org](https://www.python.org/), or any other OS package manager. |
30
41
| ms-python.python:conda|`conda`| The [conda](https://conda.org) environment manager, as provided by conda distributions like [Anaconda Distribution](https://docs.anaconda.com/anaconda/) or [conda-forge](https://conda-forge.org/download/). |
31
42
32
-
The environment manager is responsible for specifying which package manager will be used by default to install and manage Python packages within the environment. This ensures that packages are managed consistently according to the preferred tools and settings of the chosen environment manager.
43
+
Environment managers are responsible for specifying which package manager will be used by default to install and manage Python packages within the environment (`venv` uses `pip` by default). This ensures that packages are managed consistently according to the preferred tools and settings of the chosen environment manager.
33
44
34
45
### Package Management
35
46
36
-
This extension provides a package view for you to manage, install and uninstall you Python packages in any particular environment. This extension provides APIs for extension developers to contribute package managers.
47
+
The extension also provides an interface to install and uninstall Python packages, and provides APIs for extension developers to contribute package managers of their choice.
37
48
38
-
ADD A QUICK REFERENCE FOR BUTTONS
49
+
![ADD A QUICK REFERENCE PICTURE FOR BUTTONS]()
39
50
40
51
The extension uses `pip` as the default package manager. You can change this by setting the `python-envs.defaultPackageManager` setting to a different package manager. The following are package managers supported out of the box:
| ms-python.python:pip|`pip`| Pip acts as the default package manager and it's typically built-in to Python. |
45
56
| ms-python.python:conda|`conda`| The [conda](https://conda.org) package manager, as provided by conda distributions like [Anaconda Distribution](https://docs.anaconda.com/anaconda/) or [conda-forge](https://conda-forge.org/download/). |
46
57
47
-
## Command Reference
58
+
### Project Creation
59
+
60
+
The **Python: Create Project** command simplifies the process of starting a new Python project by scaffolding it for you. Whether in a new workspace or an existing one, this command sets up the necessary environment and files, so you don’t have to worry about the initial setup, and only the code you want to write.
61
+
62
+
![Gif showing project creation using the `Python: Create Project` command for a Python package.]()
48
63
49
-
| Name | Description |
50
-
| Python: Manage Packages ||
51
-
| Python: Create Project ||
52
-
| Python: Activate Environment in Current Terminal ||
53
-
| Python: Deactivate Environment in Current Terminal ||
54
-
| Python: Run as Task ||
64
+
#### Types of Projects
65
+
66
+
The `Python: Create Project` command supports the following project types:
67
+
68
+
- Package: A structured Python package with files like `__init__.py` and setup configurations.
69
+
- Generic script: A simple project for standalone Python scripts, ideal for quick tasks or just to get you started.
70
+
71
+
## Command Reference
72
+
73
+
| Name | Description |
74
+
| -------- | ------------- |
75
+
| Python: Create Environment | Create a virtual environment using your preferred environment manager preconfigured with "Quick Create" or configured to your choices. |
76
+
| Python: Manage Packages | Install and uninstall packages in a given Python environment. |
77
+
| Python: Create Project | Creates a scaffolded Python project with a virtual environment. |
78
+
| Python: Activate Environment in Current Terminal | Activates the currently opened terminal with a particular environment. |
79
+
| Python: Deactivate Environment in Current Terminal | Deactivates environment in currently opened terminal. |
80
+
| Python: Run as Task | Runs Python module as a task. |
| defaultEnvManager |`"ms-python.python:venv"`| The default environment manager used for creating and managing environments. |
61
-
| 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. |
86
+
| defaultEnvManager |`"ms-python.python:venv"`| The default environment manager used for creating and managing environments. |
87
+
| 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. |
62
88
| 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"]}`. |
63
-
| 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. |
89
+
| 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. |
64
90
65
91
## Extensibility
66
92
67
-
The Python Environments extension was built to provide a cohesive and user friendly experience with `venv` as the default. However, the extension is built with extensibility in mind so that any environment manager could build an extension using the supported APIs to plug-in and provide a seamless and incirporated experience for their users in VS Code.
93
+
The Python Environments extension was built to provide a cohesive and user friendly experience with `venv` as the default. However, the extension is built with extensibility in mind so that any environment manager could build an extension using the supported APIs to plug-in and provide a seamless and incorporated experience for their users in VS Code.
68
94
69
95
### API Reference (proposed)
70
96
71
97
See [api.ts](https://github.com/microsoft/vscode-python-environments/blob/main/src/api.ts) for the full list of Extension APIs.
72
98
73
-
To consume these APIs you can look at the example here:
To consume these APIs you can look at the example here: [API Consumption Examples](https://github.com/microsoft/vscode-python-environments/blob/main/examples/README.md)
76
100
77
101
## Extension Dependency
78
102
79
103
This section provides an overview of how the Python extension interacts with the Python Environments extension and other tool-specific extensions. The Python Environments extension allows users to create, manage, and remove Python environments and packages. It also provides an API that other extensions can use to support environment management or consume it for running Python tools or projects.
80
104
81
105
Tools that may rely on these APIs in their own extensions include:
106
+
82
107
-**Debuggers** (e.g., `debugpy`)
83
108
-**Linters** (e.g., Pylint, Flake8, Mypy)
84
109
-**Formatters** (e.g., Black, autopep8)
85
110
-**Language Server extensions** (e.g., Pylance, Jedi)
86
111
-**Environment and Package Manager extensions** (e.g., Pixi, Conda, Hatch)
87
112
88
113
### API Dependency
114
+
89
115
The relationship between these extensions can be represented as follows:
Users who do not need to execute code or work in **Virtual Workspaces** can use the Python extension to access language features like hover, completion, and go-to definition. However, executing code (e.g., running a debugger, linter, or formatter), creating/modifying environments, or managing packages requires the Python Environments extension to enable these functionalities.
94
120
@@ -98,15 +124,15 @@ VS Code supports trust management, allowing extensions to function in either **t
In **trusted mode**, the Python Environments extension supports tasks like managing environments, installing/removing packages, and running tools. In **untrusted mode**, functionality is limited to language features, ensuring a secure and restricted environment.
104
130
105
131
## Contributing
106
132
107
133
This project welcomes contributions and suggestions. Most contributions require you to agree to a
108
134
Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
109
-
the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
135
+
the rights to use your contribution. For details, visit <https://cla.opensource.microsoft.com>.
110
136
111
137
When you submit a pull request, a CLA bot will automatically determine whether you need to provide
112
138
a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions
@@ -118,17 +144,17 @@ contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additio
118
144
119
145
## Questions, issues, feature requests, and contributions
120
146
121
-
-If you have a question about how to accomplish something with the extension, please [ask on our Discussions page](https://github.com/microsoft/vscode-python/discussions/categories/q-a).
122
-
-If you come across a problem with the extension, please [file an issue](https://github.com/microsoft/vscode-python).
123
-
-Contributions are always welcome! Please see our [contributing guide](https://github.com/Microsoft/vscode-python/blob/main/CONTRIBUTING.md) for more details.
124
-
-Any and all feedback is appreciated and welcome!
125
-
- If someone has already [filed an issue](https://github.com/Microsoft/vscode-python) that encompasses your feedback, please leave a 👍/👎 reaction on the issue.
126
-
- Otherwise please start a [new discussion](https://github.com/microsoft/vscode-python/discussions/categories/ideas).
127
-
-If you're interested in the development of the extension, you can read about our [development process](https://github.com/Microsoft/vscode-python/blob/main/CONTRIBUTING.md#development-process).
147
+
- If you have a question about how to accomplish something with the extension, please [ask on our Discussions page](https://github.com/microsoft/vscode-python/discussions/categories/q-a).
148
+
- If you come across a problem with the extension, please [file an issue](https://github.com/microsoft/vscode-python).
149
+
- Contributions are always welcome! Please see our [contributing guide](https://github.com/Microsoft/vscode-python/blob/main/CONTRIBUTING.md) for more details.
150
+
- Any and all feedback is appreciated and welcome!
151
+
- If someone has already [filed an issue](https://github.com/Microsoft/vscode-python) that encompasses your feedback, please leave a 👍/👎 reaction on the issue.
152
+
- Otherwise please start a [new discussion](https://github.com/microsoft/vscode-python/discussions/categories/ideas).
153
+
- If you're interested in the development of the extension, you can read about our [development process](https://github.com/Microsoft/vscode-python/blob/main/CONTRIBUTING.md#development-process).
128
154
129
155
## Data and telemetry
130
156
131
-
The Microsoft Python Extension for Visual Studio Code collects usage data and sends it to Microsoft to help improve our products and services. Read our [privacy statement](https://privacy.microsoft.com/privacystatement) to learn more. This extension respects the `telemetry.enableTelemetry` setting which you can learn more about at https://code.visualstudio.com/docs/supporting/faq#_how-to-disable-telemetry-reporting.
157
+
The Microsoft Python Extension for Visual Studio Code collects usage data and sends it to Microsoft to help improve our products and services. Read our [privacy statement](https://privacy.microsoft.com/privacystatement) to learn more. This extension respects the `telemetry.enableTelemetry` setting which you can learn more about at <https://code.visualstudio.com/docs/supporting/faq#_how-to-disable-telemetry-reporting>.
0 commit comments