Discovering Python Installations

Understand how Positron discovers and manages Python installations. Covers automatic uv installation and support for uv, pyenv, conda, venv, and more environment managers.

This guide explains how Positron discovers and manages Python installations. For using Python in Positron, see our Python language guide.

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, as well as pixi environments created with pixi init

Other tools might also be compatible, although Positron does not officially support them.

Discovery locations

Positron searches for Python installations in the following locations. In general, it is best to use an environment that is highest in this list. Read more about why virtual environments matter.

1. Project environments

Environments associated with the open project, if you have a project folder open. In particular, Positron finds any environment at the root of the open project (for example, .venv/ or .conda/ folders).

Note

If you do not have a project open, Positron does not find any project environments, like project .venv/ folders. In general, Positron does not look across your whole system for all project-level virtual environments. Open a project folder to use that project’s environment.

2. Global environments

Positron also discovers other named environments on your system, including:

  • Custom configured environments (see the discovery settings)
  • Environments in /opt/python
  • Environments in well-known venv homes, including $WORKON_HOME, ~/.venvs, ~/.virtualenvs, and ~/.local/share/virtualenvs
  • Conda-managed named environments

3. Base interpreters

Standalone, pip-writable installs. Use these installations as seeds for new virtual environments rather than modifying them:

  • Installations from pyenv, python.org, or the Windows registry or store
  • Environment-module interpreters

4. System or externally managed interpreters

Base interpreters that you can only use for seeding virtual environments:

  • System interpreters like /usr/bin or Homebrew-installed
  • Tool-managed base interpreters, like the uv or conda base interpreters
Important

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.

The interpreter and session pickers group interpreters by environment type in a similar order, with tool-managed environments such as uv first and system interpreters last. To find an interpreter in a picker, search by its name or by part of its path.

Automatic uv installation

Positron provides the option to install Python via uv to provide an improved Python environment management experience. If you have no Python or only system Pythons, Positron offers to install uv from the Start New Console Session dropdown. When you create a Python project with New Folder From Template and choose uv, the dialog offers to install uv if it is missing.

You can control uv installation and usage in Positron in a variety of ways:

  • Disable uv installation: To never see this installation option, set python.allowUvPythonInstall to false.
  • Use existing uv: If you have uv already installed system-wide, Positron uses your existing installation.
  • Manual installation: You can also install uv yourself if you prefer to manage it directly.

You do not need uv to run Positron. Positron looks for other environment managers like venv and conda, regardless of whether uv is available.

What is uv?

uv is a modern Python package manager that provides:

  • Fast virtual environment creation
  • Efficient package installation
  • Python version management
  • Project dependency management

Positron uses uv to enhance Python workflows, including creating environments, installing packages, and managing Python versions.

Environment creation and discovery timing

Creating new environments

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

  1. Open the Command Palette with
  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)

Positron creates the environment in your workspace and automatically discovers it.

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.

Creating environments from project files

When you open a workspace that declares its dependencies but has no environment, Positron offers to create the environment for you. Positron makes this offer when the workspace has no project environment and you have a global Python selected. The offer depends on the files in the workspace:

Project files What Positron offers
uv.lock Run uv sync to create a .venv environment, then select it
pixi.lock Run pixi install to create the default pixi environment, then select it
pyproject.toml or a requirements file Create a .venv environment and install the dependencies

When uv is available and pyproject.toml is the only dependency source, Positron runs uv sync. uv then chooses the Python version, so Positron respects your uv configuration, such as python-preference.

If a uv.lock workspace needs uv and uv is missing, Positron offers to install it first. Positron cannot install pixi for you. If pixi is missing, Positron shows a warning with a link to the pixi installation instructions.

To skip the offer, click Not Now. To stop seeing it, click Don’t Show Again.

Discovering existing environments

Positron automatically discovers environments when:

  • You open Positron
  • You open a new workspace folder
  • Positron detects certain file system changes in watched directories
  • You refresh using the Interpreter: Discover All Interpreters command

The discovery process runs in the background and updates the interpreter list as Positron finds new environments.

When Positron discovers an environment inside your workspace, such as one you create in the terminal with uv venv, it offers to start a console session with that environment. Positron does not make this offer if a running session already uses the environment. To stop these offers for the workspace, click Don’t Show Again.

Other details

IPython kernel

Positron requires the IPython kernel (version 6.19.1 or higher) to communicate with Python. By default, Positron bundles the IPython kernel for the CPython implementation (the standard Python implementation) and adds it to the Python search path. This means you can use new environments immediately after Positron creates them, without installing extra dependencies.

If you prefer finer control over your Python environment, set the python.useBundledIpykernel setting to false. If you do that or are using an implementation other than CPython, install the IPython kernel yourself with pip install ipykernel.

Unsupported Python versions

Positron supports the supported versions of Python, and might continue to support end-of-life versions for a time after. Positron can discover other versions, but you might run into issues using them.

Troubleshooting

Environment not appearing

If you configure the above settings correctly, Positron supports your Python version, and Interpreter: Discover All Interpreters or a restart of Positron does not help, check the logs. See more in the troubleshooting guide. Positron logs the discovery process in the Python Locator and Python Language Pack channels.

uv installation issues

If you encounter issues with the automatic uv installation in Positron:

  1. Check network connectivity: uv installation requires internet access to download the binary.
  2. Manual installation: You can also install uv yourself if you prefer to manage it directly.
  3. Disable automatic installation: If you do not want Positron to show you uv installation, disable it by setting python.allowUvPythonInstall to false.

For detailed uv troubleshooting, refer to the uv documentation.