入门

安装uv

推荐使用官方安装脚本，无需预先安装 Python，uv 是独立的 Rust 二进制文件。

安装：

# 官方推荐方式（自动安装到 ~/.local/bin）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 或使用 pip 安装（若已有 pip）
pip install uv

# 验证安装
uv --version

更新/卸载：

uv self update          # 更新 uv 自身
uv self uninstall       # 卸载 uv

核心概念

理解 uv 的三层模型，可以更清晰地规划你的环境策略：

ℹ️ 关键文件：pyproject.toml

声明项目元数据和依赖，uv.lock 是跨平台确定性锁文件（提交到 Git），.python-version 指定项目 Python 版本。

Python版本管理

安装Python

uv 内置 Python 版本管理。所有版本独立存储，互不干扰。

# 查看所有可安装版本
uv python list
uv python list --all-versions

# 安装指定版本
uv python install 3.12
uv python install 3.11 3.10 3.9   # 同时安装多个
uv python install 3.13t               # 安装 Free-threaded 版本

# 查看已安装版本
uv python list --only-installed

# 卸载某个版本
uv python uninstall 3.9

支持的版本矩阵：

版本切换

uv 采用就近查找原则：当前目录 .python-version → 父目录逐级查找 → 全局默认。

# 在当前命令临时指定版本
uv run --python 3.11 python script.py
uv run --python 3.10 -c "import sys; print(sys.version)"

# 为当前目录/项目固定版本（写入 .python-version）
uv python pin 3.12
cat .python-version     # 输出: 3.12

# 用指定版本创建虚拟环境
uv venv --python 3.11 .venv

# 查看当前环境使用的 Python
uv python find
uv run python --version

ℹ️ 版本指定格式：3.12（最新补丁）、3.12.3（精确版本）、cpython@3.12（明确实现）、pypy@3.10（PyPy）

版本锁定

在 pyproject.toml 中声明版本约束

# pyproject.toml
[project]
name = "my-app"
version = "0.1.0"
requires-python = ">=3.11"       # 最低版本要求
# requires-python = ">=3.11,<3.13"  # 范围约束
dependencies = [
    "fastapi>=0.100",
    "uvicorn",
]

✅ 最佳实践：将 .python-version 文件提交到 Git，让团队成员和 CI/CD 使用完全相同的 Python 版本。uv.lock 同样应该提交。

环境隔离

虚拟环境

项目管理

典型工作流

依赖管理

添加依赖

锁文件

全局工具

速查

命令速查

实用技巧