uv

GitHub: https://github.com/astral-sh/uv
文档: https://docs.astral.sh/uv/

注：🚀 A single tool to replace pip, pip-tools, pipx, poetry, pyenv, virtualenv, and more.

An extremely fast Python package and project manager, written in Rust.

常用操作

uv 替换 pip（Python 包管理）:

uv pip install requests
uv pip install -r requirements.txt
uv pip uninstall requests

uv 替换 pip-tools（依赖锁定 & 解析）:

# 解析 pyproject.toml 并生成 requirements.txt
uv pip compile pyproject.toml --output-file requirements.txt

uv 替换 pipx（安装全局 CLI 工具）:

# 全局安装 CLI 工具
uv venv install httpx
# 运行 black（无需全局安装）
uv venv run black --version

uv 替换 poetry（项目依赖管理）:

# 初始化项目(生成新项目，里面有文件pyproject.toml)
uv init <proj>
# 读取 pyproject.toml 文件中的 [tool.uv.dependencies] 部分，自动安装列出的依赖库
uv pip install
# 依赖添加到你的 pyproject.toml 文件中并安装
uv add uvicorn
# 安装项目依赖(基于uv.lock)，如果没有.venv会创建
uv sync
uv sync --index-url https://mirrors.aliyun.com/pypi/simple/

uv 替换 virtualenv（虚拟环境管理）:

# 创建一个新的 Python 虚拟环境（类似 python -m venv）
# 说明：不指定<path>时，<path>=.venv
uv venv <path>

警告：⚠️ uv 不能直接替代 pyenv，但可以配合 pyenv 使用。

Project management

uv manages project dependencies and environments, with support for lockfiles, workspaces, and more, similar to rye or poetry:

$ uv init example
Initialized project `example` at `/home/user/example`
 
$ cd example
 
$ uv add ruff
Creating virtual environment at: .venv
Resolved 2 packages in 170ms
   Built example @ file:///home/user/example
Prepared 2 packages in 627ms
Installed 2 packages in 1ms
 + example==0.1.0 (from file:///home/user/example)
 + ruff==0.5.4
 
$ uv run ruff check
All checks passed!

Tool management

uv executes and installs command-line tools provided by Python packages, similar to pipx.
Run a tool in an ephemeral environment using uvx (an alias for uv tool run):

$ uvx pycowsay 'hello world!'
Resolved 1 package in 167ms
Installed 1 package in 9ms
 + pycowsay==0.0.0.2
  """
 
  ------------
< hello world! >
  ------------
   \   ^__^
    \  (oo)\_______
       (__)\       )\/\
           ||----w |
           ||     ||

Install a tool with uv tool install:

$ uv tool install ruff
Resolved 1 package in 6ms
Installed 1 package in 2ms
 + ruff==0.5.4
Installed 1 executable: ruff
 
$ ruff --version
ruff 0.5.4

Python management

uv installs Python and allows quickly switching between versions.
Install multiple Python versions:

$ uv python install 3.10 3.11 3.12
Searching for Python versions matching: Python 3.10
Searching for Python versions matching: Python 3.11
Searching for Python versions matching: Python 3.12
Installed 3 versions in 3.42s
 + cpython-3.10.14-macos-aarch64-none
 + cpython-3.11.9-macos-aarch64-none
 + cpython-3.12.4-macos-aarch64-none

Download Python versions as needed:

$ uv venv --python 3.12.0
Using Python 3.12.0
Creating virtual environment at: .venv
Activate with: source .venv/bin/activate
 
$ uv run --python pypy@3.8 -- python --version
Python 3.8.16 (a9dbdca6fc3286b0addd2240f11d97d8e8de187a, Dec 29 2022, 11:45:30)
[PyPy 7.3.11 with GCC Apple LLVM 13.1.6 (clang-1316.0.21.2.5)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>>>

Use a specific Python version in the current directory:

$ uv python pin pypy@3.11
Pinned `.python-version` to `pypy@3.11`

Script support

uv manages dependencies and environments for single-file scripts.
Create a new script and add inline metadata declaring its dependencies:

$ echo 'import requests; print(requests.get("https://astral.sh"))' > example.py
 
$ uv add --script example.py requests
Updated `example.py`
 
$ cat example.py
# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "requests",
# ]
# ///
import requests; print(requests.get("https://astral.sh"))

Then, run the script in an isolated virtual environment:

$ uv run example.py
Reading inline script metadata from: example.py
Installed 5 packages in 12ms
<Response [200]>

A pip-compatible interface

uv provides a drop-in replacement for common pip, pip-tools, and virtualenv commands.

Compile requirements into a platform-independent requirements file:

$ uv pip compile docs/requirements.in \
   --universal \
   --output-file docs/requirements.txt
Resolved 43 packages in 12ms

Create a virtual environment:

$ uv venv
Using Python 3.12.3
Creating virtual environment at: .venv
Activate with: source .venv/bin/activate

Install the locked requirements:

$ uv pip sync docs/requirements.txt
Resolved 43 packages in 11ms
Installed 43 packages in 208ms
 + babel==2.15.0
 + black==24.4.2
 + certifi==2024.7.4
 ...

⚠️ 注意事项

uv.lock 是为 uv + pyproject.toml 架构设计的，不含 channel 或平台信息，不适合直接映射到 conda。
conda 和 uv/pip 的依赖解析方式不同，存在不兼容风险，推荐用 uv 来管理 Python 包时，不要在同一环境里混装 Conda 包。
如果你需要生成 .conda-lock 文件（支持跨平台构建），请参考 conda-lock 工具，而不是 uv.lock。

目的	方法	推荐度
想用 `conda` 创建环境	导出 `requirements.txt` 再用 `conda`	⭐⭐⭐
已有 `conda` 环境	在其中用 `uv` 安装 `uv.lock` 中的依赖	⭐⭐⭐⭐
用 `conda` 管系统依赖，用 `uv` 管 Python 包	分层管理，最现代做法	⭐⭐⭐⭐⭐

与 pip / pipx / pyproject.toml 的边界

uv vs pip：uv pip <cmd> 是 pip 的高速兼容接口（同一套 CLI 语义），但 uv 的原生命令（uv add / uv sync / uv lock）走的是另一条以 pyproject.toml + uv.lock 为中心的项目管理路径，二者不要混用在同一个项目里——要么整体用 uv pip 保持 pip 习惯，要么整体切到 uv add/uv sync。
uv vs pipx：uv tool install / uvx（uv tool run 别名）对应 pipx 的”隔离环境跑 CLI 工具”场景，语义几乎一一对应，速度更快；如果项目已经全面用 uv，没必要再单独装 pipx。
uv vs pyproject.toml：uv 本身不发明新的配置格式，uv add/uv remove 操作的就是标准 [project.dependencies]，额外的 uv 专属配置写在 [tool.uv] 表里（如 workspace、index 配置），所以 uv 项目的 pyproject.toml 对其他工具（pip/build）仍然是可读的标准文件。

现代项目推荐组合

新项目：uv init 生成 pyproject.toml → uv add <pkg> 维护依赖 → uv sync 还原环境 → uv run <cmd> 执行，全程不用手动 activate 虚拟环境。
一次性运行别人的 CLI 工具：优先 uvx <tool>，不占用项目环境，也不用 pipx。
老项目迁移：先跑 uv pip install -r requirements.txt 验证兼容性，再逐步迁移到 uv add，避免一步切换导致依赖解析结果和线上不一致。
Python 版本管理：uv python install 3.12 + uv python pin 3.12，免去单独装 pyenv。

踩坑点

uv pip install 和 uv add 是两条不同的依赖记录路径：前者不会写入 pyproject.toml，后者才会，混用会导致 pyproject.toml 和实际安装的包脱节。
uv.lock 跨机器同步时要求 Python 版本约束（requires-python）一致，版本范围写得过宽会导致锁文件在不同平台解析出不同结果。
uv sync 默认会按 uv.lock 严格还原环境（多删少补），如果只是想装个新包应该用 uv add，不要手动改完 pyproject.toml 再 uv sync——顺序反了容易导致锁文件和声明不一致报错。

zhaoweiguo 的知识库

目录

uv