Back to Details

uv-python-versions

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

UV Python Version Management

UV Python 版本管理

Quick reference for installing and managing Python interpreter versions with UV.
使用 UV 安装和管理 Python 解释器版本的快速参考。

When to Use This Skill

何时使用此 Skill

Use this skill when...Use a focused sibling instead when...
Installing a specific CPython or PyPy interpreter with 
uv python install
Adding a Python library to a project — use uv-project-management
Pinning a project to a Python version via 
.python-version
or 
requires-python
Installing a global Python CLI tool — use uv-tool-management
Switching between multiple installed interpreters for testingRunning a script with auto-managed Python — use uv-run
使用此 Skill 的场景应改用更聚焦的同级 Skill 的场景
使用 
uv python install
安装特定的 CPython 或 PyPy 解释器		向项目添加 Python 库——使用 uv-project-management
通过 
.python-version
或 
requires-python
将项目固定到特定 Python 版本		安装全局 Python CLI 工具——使用 uv-tool-management
在多个已安装的解释器之间切换以进行测试使用自动管理的 Python 运行脚本——使用 uv-run

When This Skill Applies

此 Skill 的适用场景

  • Installing specific Python versions
  • Switching between multiple Python versions
  • Pinning Python versions for projects
  • Managing CPython and PyPy interpreters
  • Finding and listing installed Python versions
  • 安装特定的 Python 版本
  • 在多个 Python 版本之间切换
  • 为项目固定 Python 版本
  • 管理 CPython 和 PyPy 解释器
  • 查找并列出已安装的 Python 版本

Quick Reference

快速参考

Installing Python Versions

安装 Python 版本

bash
undefined
bash
undefined

Install latest Python

Install latest Python

uv python install
uv python install

Install specific version

Install specific version

uv python install 3.11 uv python install 3.12 uv python install 3.10 3.11 3.12
uv python install 3.11 uv python install 3.12 uv python install 3.10 3.11 3.12

Install exact version

Install exact version

uv python install 3.11.5 uv python install cpython@3.11.5
uv python install 3.11.5 uv python install cpython@3.11.5

Install PyPy

Install PyPy

uv python install pypy@3.9 uv python install pypy@3.10
undefined
uv python install pypy@3.9 uv python install pypy@3.10
undefined

Listing Python Versions

列出 Python 版本

bash
undefined
bash
undefined

List all available versions

List all available versions

uv python list
uv python list

List only installed versions

List only installed versions

uv python list --only-installed
uv python list --only-installed

List with verbose details

List with verbose details

uv python list --verbose
undefined
uv python list --verbose
undefined

Pinning Python Versions

固定 Python 版本

bash
undefined
bash
undefined

Pin version for current project

Pin version for current project

uv python pin 3.11 uv python pin 3.12.1
uv python pin 3.11 uv python pin 3.12.1

Pin PyPy

Pin PyPy

uv python pin pypy@3.9
uv python pin pypy@3.9

Pin with version file

Pin with version file

Creates/updates .python-version

Creates/updates .python-version

undefined
undefined

Finding Python Interpreters

查找 Python 解释器

bash
undefined
bash
undefined

Find any Python installation

Find any Python installation

uv python find
uv python find

Find specific version

Find specific version

uv python find 3.11 uv python find 3.12
uv python find 3.11 uv python find 3.12

Find PyPy

Find PyPy

uv python find pypy uv python find pypy@3.9
undefined
uv python find pypy uv python find pypy@3.9
undefined

Using Specific Python Versions

使用特定 Python 版本

bash
undefined
bash
undefined

In project commands

In project commands

uv run --python 3.11 script.py uv run --python 3.12 pytest
uv run --python 3.11 script.py uv run --python 3.12 pytest

Creating virtual environments

Creating virtual environments

uv venv --python 3.11 uv venv --python 3.10 .venv-py310
uv venv --python 3.11 uv venv --python 3.10 .venv-py310

Initializing projects

Initializing projects

uv init --python 3.12 my-project
undefined
uv init --python 3.12 my-project
undefined

Python Version Sources

Python 版本来源

UV searches for Python in this order:
  1. UV-managed - Installed via 
    uv python install
  2. .python-version - Pin file in project directory
  3. pyproject.toml - 
    requires-python
    field
  4. System Python - Existing system installations
  5. Environment - 
    $PATH
    and standard locations
UV 按以下顺序查找 Python：
  1. UV 管理的版本——通过 
    uv python install
    安装
  2. .python-version——项目目录中的版本固定文件
  3. pyproject.toml——
    requires-python
    字段
  4. 系统 Python——现有的系统安装
  5. 环境——
    $PATH
    和标准位置

Version Pinning

版本固定

.python-version File

.python-version 文件

bash
undefined
bash
undefined

Pin creates this file

Pin creates this file

uv python pin 3.11
uv python pin 3.11

File contents

File contents

3.11
3.11

Exact version

Exact version

uv python pin 3.11.5
undefined
uv python pin 3.11.5
undefined

pyproject.toml

pyproject.toml

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

UV respects this constraint

UV respects this constraint

undefined
undefined

Supported Python Implementations

支持的 Python 实现

CPython

CPython

bash
undefined
bash
undefined

Default implementation

Default implementation

uv python install 3.11 uv python install cpython@3.11 uv python install cpython@3.11.5
undefined
uv python install 3.11 uv python install cpython@3.11 uv python install cpython@3.11.5
undefined

PyPy

PyPy

bash
undefined
bash
undefined

Alternative Python implementation

Alternative Python implementation

uv python install pypy@3.9 uv python install pypy@3.10
undefined
uv python install pypy@3.9 uv python install pypy@3.10
undefined

Common Commands

常用命令

bash
undefined
bash
undefined

Install and pin latest Python 3.12

Install and pin latest Python 3.12

uv python install 3.12 && uv python pin 3.12
uv python install 3.12 && uv python pin 3.12

Install multiple versions for testing

Install multiple versions for testing

uv python install 3.10 3.11 3.12
uv python install 3.10 3.11 3.12

Check which Python is active

Check which Python is active

uv python find uv run python --version
uv python find uv run python --version

Uninstall version (manual)

Uninstall version (manual)

rm -rf ~/.local/share/uv/python/cpython-3.11.5-*
undefined
rm -rf ~/.local/share/uv/python/cpython-3.11.5-*
undefined

Integration with Projects

与项目的集成

Project Initialization

项目初始化

bash
undefined
bash
undefined

Initialize with specific Python

Initialize with specific Python

uv init --python 3.11 my-project
uv init --python 3.11 my-project

Generates .python-version

Generates .python-version

cat .python-version
cat .python-version

3.11

3.11

undefined
undefined

Running Commands

运行命令

bash
undefined
bash
undefined

Use project's pinned Python

Use project's pinned Python

uv run python script.py
uv run python script.py

Override with specific version

Override with specific version

uv run --python 3.12 script.py
uv run --python 3.12 script.py

Use system Python

Use system Python

uv run --python python3 script.py
undefined
uv run --python python3 script.py
undefined

Multi-Version Testing

多版本测试

bash
undefined
bash
undefined

Test across Python versions

Test across Python versions

uv run --python 3.10 pytest uv run --python 3.11 pytest uv run --python 3.12 pytest
uv run --python 3.10 pytest uv run --python 3.11 pytest uv run --python 3.12 pytest

Create version-specific venvs

Create version-specific venvs

uv venv --python 3.10 .venv-py310 uv venv --python 3.11 .venv-py311 uv venv --python 3.12 .venv-py312
undefined
uv venv --python 3.10 .venv-py310 uv venv --python 3.11 .venv-py311 uv venv --python 3.12 .venv-py312
undefined

Key Features

主要功能

  • Fast downloads: Parallel downloads with caching
  • Automatic: Downloads versions on-demand
  • Isolated: UV-managed versions don't conflict with system Python
  • Portable: Uses standalone Python distributions
  • Cross-platform: Works on Linux, macOS, and Windows
  • 快速下载：利用缓存进行并行下载
  • 自动化：按需下载版本
  • 隔离性：UV 管理的版本不会与系统 Python 冲突
  • 可移植性：使用独立的 Python 发行版
  • 跨平台：适用于 Linux、macOS 和 Windows

See Also

另请参阅

  • uv-project-management
    - Using pinned Python versions in projects
  • uv-workspaces
    - Python versions in monorepos
  • python-testing
    - Testing across multiple Python versions
  • uv-project-management
    ——在项目中使用固定的 Python 版本
  • uv-workspaces
    ——monorepo 中的 Python 版本
  • python-testing
    ——在多个 Python 版本上进行测试

References

参考资料