Python 包管理器uv

new【一个】对象2026-05-12 10:51

uv 是由 Astral 团队（就是开发了 Python 代码检查工具 ruff 的那个团队）用 Rust 编写的极速 Python 包管理器和项目管理工具 。它的目标是成为 pip、pip-tools、virtualenv、poetry、pyenv 等多种工具的统一替代品，并且速度比它们快 10-100 倍。

下面是一份详细的 uv 使用指南，涵盖了它能做的几乎所有事情。

1. uv 可以做什么？一图/一表概览

传统工具/组合 对应 uv 命令 功能说明
pip install uv pip install 安装 Python 包
pip list uv pip list 列出已安装的包
pip freeze uv pip freeze 导出 requirements 文件
pip-compile (pip-tools) uv pip compile 从宽松依赖生成精确锁定文件
pip-sync (pip-tools) uv pip sync 让环境与锁定文件严格同步
virtualenv / python -m venv uv venv 创建虚拟环境
poetry / pdm / hatch 项目管理 uv init / uv add / uv lock / uv sync / uv run 项目级依赖管理与脚本运行
pyenv / python-build uv python install / uv python list 下载与管理 Python 版本
pipx uv tool install / uv tool run 安装和运行命令行工具到隔离环境
python script.py uv run script.py 直接运行 Python 脚本（自动创建临时环境）
全局缓存管理 uv cache clean / uv cache dir 查看和清理 uv 的包缓存

简单来说，uv 可以：

  • 管理 Python 版本：像 pyenv 一样下载和切换 Python 解释器。

  • 管理虚拟环境：创建和操作虚拟环境。

  • 当作极速的 pip 替代品：安装包快得飞起。

  • 管理项目 ：像 Poetry 那样用 pyproject.toml 定义依赖，自动锁定依赖。

  • 运行工具 ：像 pipx 那样全局安装 Python 命令行工具。

  • 运行脚本：为单个脚本自动管理临时环境，一行命令即可运行含有依赖声明的脚本。

2. 安装 uv

官方推荐方式（Linux / macOS / WSL）：

bash

复制代码 
curl -LsSf https://astral.sh/uv/install.sh | sh

Windows：

powershell

复制代码 
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

使用 pip（如果你已有 Python）：

bash

复制代码 
pip install uv

使用包管理器：

  • macOS Homebrew: brew install uv

  • Windows Scoop: scoop install uv

  • Arch Linux: pacman -S uv

  • 其他见官方文档。

安装后验证：

bash

复制代码 
uv --version

3. 管理 Python 版本（pyenv 替代）

uv 可以下载和管理 Python 解释器，无需安装 pyenv。

bash

复制代码 
# 查看可安装的 Python 版本
uv python list

# 只列出下载好的本地版本
uv python list --only-installed

# 安装指定 Python 版本（自动下载，无需管理员权限）
uv python install 3.12

# 安装 CPython 或 PyPy
uv python install pypy@3.10

# 查找已安装 Python 的路径
uv python find 3.12

你可以在创建虚拟环境时指定 Python 版本，如果未安装，它会自动下载。

4. 极速 pip 替代（uv pip 子命令）

uv 的 pip 接口与标准 pip 命令高度兼容，但速度极快，且解析依赖（resolving）更可靠。

4.1 安装包

bash

复制代码 
# 创建虚拟环境（比 venv 快得多）
uv venv

# 激活环境（Windows: .venv\Scripts\activate）
# Linux/macOS:
source .venv/bin/activate

# 安装包（无需先激活也可，指定环境路径）
uv pip install flask

# 指定安装到某个虚拟环境
uv pip install flask --python .venv/bin/python

# 安装多个包
uv pip install requests numpy pandas

# 从 requirements.txt 安装
uv pip install -r requirements.txt

# 安装可编辑项目
uv pip install -e .

4.2 生成锁定文件（替代 pip-compile）

bash

复制代码 
# 从 requirements.in 生成精确的 requirements.txt
uv pip compile requirements.in -o requirements.txt

# 从 pyproject.toml 的依赖生成锁定文件
uv pip compile pyproject.toml -o requirements.txt

# 升级所有依赖到最新兼容版本
uv pip compile requirements.in --upgrade -o requirements.txt

# 生成带哈希检查的锁定文件
uv pip compile requirements.in --generate-hashes -o requirements.txt

4.3 环境同步（替代 pip-sync）

uv pip sync 会精准地让环境与锁定文件一致，移除多余包，安装缺失包。

bash

复制代码 
# 严格与 requirements.txt 同步
uv pip sync requirements.txt

# 使用不同 Python 环境同步
uv pip sync requirements.txt --python ./venv/bin/python

4.4 列出和卸载包

bash

复制代码 
# 列出已安装包
uv pip list

# 导出当前环境
uv pip freeze > requirements.txt

# 卸载包
uv pip uninstall flask

5. 项目级管理（Poetry / PDM 替代）

这是 uv 最强大的模式：在项目中使用 pyproject.toml 作为单一依赖声明文件，结合锁文件和虚拟环境。

5.1 初始化项目

bash

复制代码 
# 创建新项目目录并初始化
uv init my-project
cd my-project
# 这会生成 pyproject.toml、README.md、.python-version 等

# 在已有目录中初始化
uv init --name my-app

生成的 pyproject.toml 大概这样：

toml

复制代码 
[project]
name = "my-app"
version = "0.1.0"
description = "My package"
requires-python = ">=3.12"
dependencies = []

5.2 添加和移除依赖

bash

复制代码 
# 添加依赖（自动更新 pyproject.toml 和 uv.lock）
uv add requests

# 添加开发依赖
uv add --dev pytest black

# 添加可选依赖组（如 extra: "web"）
uv add fastapi --optional web

# 从锁定文件和 pyproject.toml 移除
uv remove requests

# 升级某个包
uv add requests --upgrade

5.3 锁定依赖（生成 uv.lock）

uv add 会自动生成 uv.lock 文件，你也可以手动锁定：

bash

复制代码 
uv lock
# 或升级全部依赖
uv lock --upgrade

uv.lock 是跨平台的精确锁定文件，记录了每个包的具体版本、哈希和所支持的标记（markers），确保可重现。

5.4 同步环境（安装所有依赖）

bash

复制代码 
# 在项目目录下，根据 uv.lock 将环境同步到完美状态
uv sync

# 只安装生产依赖，跳过开发依赖
uv sync --no-dev

# 安装特定的额外依赖组
uv sync --extra web

uv sync 会自动创建一个 .venv 虚拟环境（如果没有的话），并严格同步所有依赖。

5.5 运行命令和脚本

bash

复制代码 
# 在项目虚拟环境中运行任意命令
uv run python my_script.py

# 运行直接引用的包提供的命令行工具
uv run pytest

# 如果只想激活 shell
uv shell  # 启动一个在当前环境中的子 shell
# 或直接激活 .venv
source .venv/bin/activate

uv run 可以不需要先手动激活环境，始终保持依赖隔离。

5.6 构建和发布

bash

复制代码 
# 构建 sdist 和 wheel
uv build

# 发布到 PyPI（需要设置凭证）
uv publish

6. 工具管理（pipx 替代）

uv 可以像 pipx 一样把 Python 包安装成隔离的全局命令行工具。

bash

复制代码 
# 安装一个工具
uv tool install ruff

# 安装时指定版本
uv tool install ruff==0.4.0

# 列出已安装的工具
uv tool list

# 升级工具
uv tool upgrade ruff

# 卸载
uv tool uninstall ruff

# 临时运行一个工具（不永久安装）
uv tool run pycowsay "Hello uv!"

# 另一种临时运行方式（与上面类似）
uvx ruff check .
# `uvx` 是 `uv tool run` 的快捷别名

uvx 非常方便，可直接在命令行中运行一次性工具：

bash

复制代码 
uvx httpie https://httpbin.org/json

7. 脚本运行（单文件项目）

借鉴 PEP 723 规范，uv 可以直接运行带有内嵌依赖声明的 Python 脚本。

例如 my_script.py：

python

复制代码 
# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "requests",
#     "rich",
# ]
# ///
import requests
from rich import print

r = requests.get("https://api.github.com/repos/astral-sh/uv")
data = r.json()
print(f"[bold]{data['full_name']}[/bold]: {data['stargazers_count']} stars")

然后直接运行：

bash

复制代码 
uv run my_script.py

uv 会自动创建一个临时虚拟环境，安装 requests 和 rich，然后执行脚本。再也不用为了一个小脚本手动创建虚拟环境了。

8. 缓存管理

uv 使用全局缓存来加速重复下载和重建。

bash

复制代码 
# 查看缓存位置
uv cache dir

# 查看缓存占用大小
uv cache prune --dry-run

# 清理未使用的包
uv cache prune

# 彻底清空所有缓存
uv cache clean

9. 配置 uv

uv 支持多种配置方式：命令行参数、环境变量、配置文件。

  • 配置文件 ：pyproject.toml 中的 [tool.uv] 部分，或用户级 ~/.config/uv/uv.toml。

  • 环境变量 ：如 UV_PYTHON、UV_CACHE_DIR、UV_INDEX_URL、UV_LINK_MODE 等。

常用配置示例 (~/.config/uv/uv.toml)：

toml

复制代码 
[pip]
index-url = "https://pypi.org/simple"

或者在项目的 pyproject.toml 中：

toml

复制代码 
[tool.uv]
dev-dependencies = ["pytest>=7.0"]

[tool.uv.sources]
# 自定义包源

10. 真实项目工作流速览

从头创建一个 Flask 项目

bash

复制代码 
# 1. 创建一个项目
uv init flask-app
cd flask-app

# 2. 设置需要的 Python 版本（自动下载）
uv python pin 3.12

# 3. 添加依赖
uv add flask

# 4. 创建源码目录和应用文件
mkdir src
echo 'from flask import Flask
app = Flask(__name__)
@app.route("/")
def hello():
    return "Hello from uv!"
' > src/app.py

# 5. 运行应用
uv run flask --app src/app run

接手一个已经使用 uv 的项目

bash

复制代码 
git clone https://github.com/someone/some-uv-project.git
cd some-uv-project
uv sync
uv run pytest

迁移现有项目到 uv

如果你的项目已有 requirements.txt 或 Poetry 的 pyproject.toml：

bash

复制代码 
# 从 requirements.txt 添加依赖
uv add -r requirements.txt

# 如果有 poetry.lock 或已定义 dependencies，uv也会尽量识别
# 初始化后生成 uv.lock：
uv lock

11. 与其它工具的速度/体验对比

  • 解析速度 ：uv 的依赖解析器是用 Rust 从零实现的，在复杂依赖树上比 pip 和 Poetry 快很多。

  • 安装速度：得益于大量并行下载和使用硬链接/复制缓存，避免了重复下载和构建。

  • 磁盘效率：同一版本包在多个虚拟环境间通过硬链接或写时复制（copy-on-write）共享，占用空间极小。

  • 跨平台锁定 ：uv.lock 支持标记（markers），单一锁文件可在不同操作系统和 Python 版本下通用，比 poetry.lock 更灵活。

总结

uv 几乎统一了 Python 开发中所有与环境和依赖相关的环节：Python 下载 → 环境创建 → 依赖解析 → 包安装 → 锁定文件 → 项目运行 → 工具安装 → 发布 。你可以渐进式地使用它（比如只把它当作飞快的 pip 替代），也可以将整个项目工作流迁移过来。

官方文档非常出色，是进一步深入的最佳路径：

👉 https://docs.astral.sh/uv

相关推荐
狐狐生风1 小时前
Python UV 完整安装教程
开发语言·python·uv
m0_591364731 小时前
Python如何进行数据平滑处理_使用Pandas滚动中位数计算
jvm·数据库·python
智塑未来1 小时前
高精度3D室内定位设备如何赋能机器人科研创新
人工智能·安全
captain_AIouo1 小时前
Captain AI全功能矩阵覆盖OZON运营每一个关键节点
大数据·人工智能·经验分享·矩阵·aigc
机器之心1 小时前
OpenAI杀疯了！砸40亿美元成立新公司、还祭出网络防御利器Daybreak
人工智能·openai
Kiyra1 小时前
限流不是加个计数器就行：用 Lua 脚本实现多维度原子限流
开发语言·人工智能·网络协议·职场和发展·架构·lua·ai-native
生物信息与育种1 小时前
生信数据格式，是否该为人工智能重新设计了？
人工智能
killerbasd1 小时前
总结 5.11
人工智能·机器学习
一只AI打工虾的自我修养1 小时前
DeepSeek V4.1 vs Ollama vs LocalClaw：Mac本地AI工具横评
人工智能·windows·macos
热门推荐
01GitHub 镜像站点02Codex 接入 DeepSeek API 完整配置文档03【AI】2026 年具身智能模型和世界模型总结04CC-Switch & Claude 基于 Linux 服务器安装使用指南05零基础教你claude code 接入 deepseek V406Windows端Codex接入第三方模型（DeekSeek，BaiLian)07Cursor 接入 DeepSeek‑V4‑Pro 完整指南（2026 实测）08要裂开了！ChatGPT要手机号验证了？注册Codex要求验证电话号码怎么办？2026年登陆Codex要手机号验证的解决办法092026年AI前瞻：量子AI、具身智能与科学发现的新纪元10裂开！ChatGPT 居然开始要手机号验证，附详细解决方法