uv常用操作：Python、脚本、工具与项目管理

Python版本、虚拟环境、项目依赖和临时命令行工具原本分散在不同工具中，uv把它们收进了一套命令。日常开发基本可以围绕uv python、uv run、uv tool和项目命令完成，使用的uv版本为0.12.5。

参考

macOS和Linux可以使用官方安装脚本：

curl -LsSf https://astral.sh/uv/install.sh | sh
uv --version

通过Homebrew安装：

brew install uv

uv可以安装多个Python版本，也能直接使用系统中已有的Python：

uv python install 3.10 3.11 3.12
uv python list

在项目中固定Python版本，会生成.python-version：

uv python pin 3.11

创建指定版本的虚拟环境：

uv venv --python 3.12
source .venv/bin/activate

只指定3.12比固定到某个补丁版本更省事，uv会选择满足条件的版本。

临时指定默认索引：

uv add \
  --default-index https://pypi.tuna.tsinghua.edu.cn/simple \
  requests

也可以使用环境变量：

export UV_DEFAULT_INDEX=https://pypi.tuna.tsinghua.edu.cn/simple

项目的pyproject.toml使用[[tool.uv.index]]：

[[tool.uv.index]]
name = "mirror"
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true

独立的uv.toml没有tool.uv前缀：

[[index]]
name = "mirror"
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true

用户级配置可以放在~/.config/uv/uv.toml。uv tool属于用户级操作，不读取项目中的索引配置，需要使用用户级配置、环境变量或命令行参数。

临时给脚本增加依赖，不会修改当前项目：

uv run --with rich example.py
uv run --with 'rich>12,<13' example.py
uv run --python 3.10 example.py

需要长期保留依赖时，可以把PEP723元数据写进脚本：

uv init --script example.py --python 3.12
uv add --script example.py 'requests<3' rich
uv run example.py

脚本默认不会自动生成锁文件。需要固定依赖时单独锁定：

uv lock --script example.py

锁文件会写到脚本旁边，例如example.py.lock。

偶尔使用的工具直接通过uvx运行。它是uv tool run的简写，每个工具使用独立的临时环境：

uvx ruff check .
uv tool run ruff check .

uvx --from httpie http --version
uvx ruff@0.3.0 check .
uvx --with mkdocs-material mkdocs --help

经常使用的工具可以持久安装：

uv tool install 'ruff>=0.4'
uv tool update-shell
ruff --version

版本范围要加引号，否则Shell可能把>识别成输出重定向。

查看、升级和删除工具：

uv tool list
uv tool upgrade ruff
uv tool upgrade --all
uv tool uninstall ruff

工具需要特定Python版本时显式指定：

uvx --python 3.10 ruff
uv tool install --python 3.10 ruff
uv tool upgrade --python 3.10 ruff

创建项目并添加依赖：

uv init hello-world
cd hello-world

uv add requests
uv add 'requests==2.31.0'
uv add git+https://github.com/psf/requests

从现有依赖文件迁移：

uv add -r requirements.txt -c constraints.txt

删除或升级单个依赖：

uv remove requests
uv lock --upgrade-package requests

uv.lock记录完整的解析结果，uv sync将项目环境同步到锁文件：

uv lock
uv sync

uv run会在运行前自动检查锁文件并同步环境，通常不需要手工激活.venv：

uv run python main.py

uv add flask
uv run flask run -p 3000

CI中不希望命令悄悄修改锁文件时，可以使用--locked：

uv sync --locked
uv run --locked python main.py

uv build
uv publish

构建产物位于dist/。发布前需要在目标包索引中配置认证；如果项目配置了多个索引，使用uv publish --index <name>明确指定发布目标。