Managing Python

Install, switch, and manage Python versions with uv

Overview

uv can detect and use existing Python installations, but it can also install and manage Python versions for you. Python is automatically downloaded when needed — you don’t need to install it first.

Python doesn’t publish official distributable binaries. uv uses distributions from Astral’s python-build-standalone project. See Python distributions for details.

Getting started

1. Install the latest Python

   uv python install
   

   This installs the latest stable Python version.

2. Use the installed Python

   uv automatically uses installed versions:

   python3.13
   

   By default, uv only installs versioned executables (e.g., python3.13).

3. Install default executables (experimental)

   To also install python and python3 executables:

   uv python install --default
   

See installing Python executables for more details.

Installing specific versions

Install any Python version you need:

Specific minor version

uv python install 3.12

uv python install 3.11 3.12

uv python install pypy@3.10

uv python install 3.11.8

See python install documentation for all options.

Viewing Python installations

List available and installed Python versions:

uv python list

This shows:

• Installed versions (uv-managed and system)
• Available versions for download
• Version details (implementation, architecture)

List all available

uv python list

uv python list --only-installed

uv python list 3.12

See python list for more details.

Automatic Python downloads

Python is downloaded automatically when needed:

# Downloads Python 3.12 if not installed
uvx python@3.12 -c "print('hello world')"

Even without a specific version request:

# Downloads latest Python if none exists
uv venv

Automatic downloads can be easily disabled if you want more control.

Using existing Python versions

uv automatically discovers and uses system Python installations. No configuration needed!

Force system Python

Prevent uv from using managed Python versions:

uv venv --no-managed-python

See Python version preference for more details.

Pinning Python versions

In projects

The .python-version file pins the Python version for a project:

echo "3.12" > .python-version

uv uses this file when creating virtual environments for the project.

With pyenv compatibility

uv respects .python-version files created by pyenv:

pyenv local 3.11.8
# Creates .python-version with "3.11.8"

uv venv
# Uses Python 3.11.8

Upgrading Python versions

Upgrading Python patch versions is in preview and may change.

Upgrade to the latest supported patch release:

Upgrade specific version

uv python upgrade 3.12

uv python upgrade

This updates minor versions to their latest patch (e.g., 3.12.0 → 3.12.7).

See python upgrade documentation.

Reinstalling Python

Reinstall uv-managed Python versions:

uv python install --reinstall

This reinstalls all previously installed Python versions. Useful for:

• Fixing corrupted installations
• Getting improvements to Python distributions
• Resolving platform-specific issues

Improvements are constantly added to Python distributions, so reinstalling may resolve bugs even if the version number doesn’t change.

Switching Python versions

In projects

1. Check current version

   cat .python-version
   # 3.12
   
2. Change version

   echo "3.11" > .python-version
   
3. Recreate environment

   rm -rf .venv
   uv sync
   

For specific commands

Use --python to override the Python version:

Run with specific version

uv run --python 3.10 main.py

uv venv --python 3.11

uv tool install --python 3.12 ruff

Working with multiple Python versions

Install all versions you need

uv python install 3.10 3.11 3.12 3.13

Test across versions

for version in 3.10 3.11 3.12; do
  echo "Testing with Python $version"
  uv run --python $version pytest
done

Build with specific versions

# Build wheels for multiple Python versions
uv build --python 3.11
uv build --python 3.12

Complete workflow examples

Setting up a new project

1. Install Python

   uv python install 3.12
   
2. Create project

   uv init my-project
   cd my-project
   
3. Verify Python version

   cat .python-version
   # 3.12
   
4. Start developing

   uv add httpx
   uv run main.py
   

Migrating to a newer Python version

1. Install new Python

   uv python install 3.13
   
2. Update project

   echo "3.13" > .python-version
   
3. Update pyproject.toml

   [project]
   requires-python = ">=3.13"
   
4. Recreate environment

   rm -rf .venv
   uv sync
   
5. Test everything

   uv run pytest
   

Working with PyPy

1. Install PyPy

   uv python install pypy@3.10
   
2. Create PyPy environment

   uv venv --python pypy@3.10
   
3. Use PyPy

   uv run --python pypy@3.10 main.py
   

Best practices

Pin Python versions in projects

Always create a .python-version file in your project:

uv init my-project  # Automatically creates .python-version

This ensures all team members use the same Python version.

Specify requires-python in pyproject.toml

Set minimum Python version in your project metadata:

[project]
requires-python = ">=3.11"

This documents compatibility and prevents installation on older Python.

Keep Python versions updated

Regularly upgrade to latest patch releases:

uv python upgrade

Patch releases include security fixes and bug improvements.

Test across Python versions

Install and test with multiple Python versions:

uv python install 3.11 3.12 3.13

Use CI/CD to automate testing across versions.

Troubleshooting

Python version not found

Install the specific version:

uv python install 3.12.7

Or list available versions:

uv python list 3.12

Wrong Python version used

Check version resolution:

# In a project
cat .python-version

# Check what uv would use
uv python find

Override with --python:

uv run --python 3.12 main.py

Automatic downloads not working

Check if automatic downloads are disabled:

# Enable automatic downloads
export UV_PYTHON_DOWNLOADS=automatic

Or explicitly install:

uv python install 3.12

Environment issues after Python upgrade

Recreate the virtual environment:

rm -rf .venv
uv sync

Virtual environments are tied to specific Python installations.

Next steps

Python versions concept

Deep dive into Python version management

Command reference

View all uv python commands

Running scripts

Execute Python scripts with uv

Working with projects

Create and manage projects