Skip to main content

​
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: 
uv python install 3.12
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)
uv python list
See python list for more details.

​
Automatic Python downloads

Python is downloaded automatically when needed: 
# Downloads Python 3.12 if not installed
uvx [email protected] -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: 
uv python upgrade 3.12
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: 
uv run --python 3.10 main.py

​
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 [email protected]
2

Create PyPy environment

uv venv --python [email protected]
3

Use PyPy

uv run --python [email protected] main.py

​
Best practices

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.
Set minimum Python version in your project metadata:
[project]
requires-python = ">=3.11"
This documents compatibility and prevents installation on older Python.
Regularly upgrade to latest patch releases:
uv python upgrade
Patch releases include security fixes and bug improvements.
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

Install the specific version:
uv python install 3.12.7
Or list available versions:
uv python list 3.12
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
Check if automatic downloads are disabled:
# Enable automatic downloads
export UV_PYTHON_DOWNLOADS=automatic
Or explicitly install:
uv python install 3.12
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

Build docs developers (and LLMs) love

Get started for freeTalk to us