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:

  • venv: Standard library virtual environments created with python -m venv
  • uv: Virtual environments and Python installations managed by uv
  • pyenv: Python installations managed by pyenv, including virtual environments
  • conda: Conda environments created with conda create or mamba create

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 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 about this). For that reason, we recommend using virtual environments.

Custom locations

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 (Cmd/Ctrl+Shift+P)
  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 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. 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 ("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.

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.