positron-website/python-installations.qmd at 7d33a0cacdf453e190982c756cc7e8123b75ae92 · posit-dev/positron-website · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
---
title: "Discovering Python Installations"
---

This guide explains how Python installations are discovered and managed in Positron.

## Python installation discovery

Positron uses multiple strategies to discover Python interpreters and virtual environments across your system.
The discovery process includes both global Python installations and various virtual environment managers.

### Supported environment managers

Positron supports the following Python environment managers:

{{< include "_python-managers.qmd" >}}

Other tools may also be compatible, although they are not officially supported at this time.

### Discovery locations

Positron searches for Python interpreters in the following locations:

**Virtual environments**

* `.venv/` and `.conda/` folders in your [workspace](https://code.visualstudio.com/docs/editing/workspaces/workspaces#_singlefolder-workspaces) directory
* Tool-managed project-specific installations in locations like `~/.local/share/virtualenvs` or where `conda` stores envs

**Global Python installations**

* System Python installations in standard locations like the user's `PATH`
* `/opt/python`
* Tool-managed installation locations like `~/.pyenv` or ` ~/.local/share/uv/python/`

Note that using a system Python installation in a new session can lead to problems (see the official [guidance](https://packaging.python.org/en/latest/specifications/externally-managed-environments/) about this).
For that reason, we recommend using virtual environments.

**Custom locations**

* Interpreters listed in the [`python.interpreters.[include,exclude,override]` settings](positron://settings/python.interpreters.include) (see [Related Settings](#related-settings) below for details)

## Environment creation and discovery

### Creating new environments

You can create new Python environments directly from Positron using the _Python: Create Environment_ command:

1. Open the Command Palette (<kbd>Cmd/Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd>)
2. Select _Python: Create Environment_
3. Choose from available environment providers:
   - **uv**: Creates a uv-managed virtual environment (if uv is available)
   - **venv**: Creates a standard virtual environment using `python -m venv`
   - **conda**: Creates a conda environment (if conda is available)

The environment will be created in your workspace and automatically discovered.

You can also use the [New Folder From Template feature](folder-templates.qmd#new-folder-from-template) to create a new Python project, and set up an environment as part of the project.

### Discovering existing environments

Positron automatically discovers environments when:

- You open Positron
- You open a new workspace folder
- Certain file system changes are detected in watched directories
- You manually refresh using the _Interpreter: Discover All Interpreters_ command

The discovery process runs in the background and updates the interpreter list as new environments are found.

## Discovery process details

### Unsupported Python versions

Positron only supports Python minor versions 3.9 through 3.13, which are the [currently supported versions](https://devguide.python.org/versions/).
Other versions may be discovered, but you may run into issues using them.

### Locator type

Positron can use two different discovery mechanisms:

* **JavaScript locator** (default): Pure TypeScript implementation for more comprehensive discovery
* **Native locator** (experimental): Uses a native binary for faster discovery

You can control this with the [`python.locator` setting](positron://settings/python.locator) (`"js"` or `"native"`).
Keep in mind that the `native` locator is experimental and may not work completely as intended.

## Troubleshooting

### Environment not appearing

If the above settings are configured correctly, and the Python version is supported, and _Interpreter: Discover All Interpreters_ or a restart of Positron is not helping, you can check logs. See more in the [troubleshooting guide](troubleshooting.qmd).

For the `js` (default) locator, the discovery process is logged in the Python Language Pack channel of the Output panel.

For the `native` locator, it is instead logged in the Python Locator channel.

## Related settings

Key settings that control Python environment discovery:

### Discovery location settings
* [`python.interpreters.include`](positron://settings/python.interpreters.include): Specific interpreter paths to include
* [`python.interpreters.exclude`](positron://settings/python.interpreters.exclude): Interpreter paths to exclude from discovery
* [`python.interpreters.override`](positron://settings/python.interpreters.override): Override the above two settings so only these are shown

### Environment providers
* [`python.environmentProviders.enable`](positron://settings/python.environmentProviders.enable): Enable/disable specific environment providers for environment creation (`Venv`, `Conda`, `uv`)

### Discovery behavior
* [`python.locator`](positron://settings/python.locator): Choose between "native" or "js" discovery methods
* [`python.defaultInterpreterPath`](positron://settings/python.defaultInterpreterPath): Default Python interpreter path (used only the first time when no other interpreter takes precedence)

## Related commands

* _Interpreter: Discover All Interpreters_: Find new interpreters
* _Interpreter: Select Interpreter Session_: Select an interpreter for a session
* _Python: Create Environment_: Create a new virtual environment