reference 速查手册：uv —— 用 Rust 打造极速 Python 包与项目管理工具-港品优选

reference 速查手册：uv —— 用 Rust 打造极速 Python 包与项目管理工具

【免费下载链接】reference面向开发者的技术速查清单（Cheat Sheets）集合，整理常见技术、工具与开发流程，帮助快速查阅关键信息，提高开发效率。项目地址: https://gitcode.com/GitHub_Trending/referen/reference

uv 是一个用 Rust 编写的极速 Python 包与项目管理工具，它同时覆盖依赖解析、虚拟环境、Python 版本管理和项目构建等环节，正逐渐成为 Python 开发者日常流程的核心替代方案。本文以本项目 docs/uv.md 备忘清单为主体，结合当前仓库的组织方式，系统整理 uv 的安装、项目初始化、依赖管理、脚本运行与构建打包等实战用法，读完即可用一条命令链跑通"建项目 → 加依赖 → 跑代码 → 出包"的完整流程。

uv 是什么

uv 由 Rust 生态工具链团队（ruff 作者所在团队）开发，定位是Python 包和项目管理工具。它用一个二进制整合了传统上分散在pip、virtualenv、pip-tools、poetry等工具中的能力：

包安装与依赖解析：替代pip/pip-tools，输出可重复安装的锁定文件；
虚拟环境管理：创建、激活、自动发现并复用项目虚拟环境；
Python 版本管理：下载、安装并固定项目所需的解释器版本；
项目构建：基于pyproject.toml构建 wheel 与 sdist 产物。

在本仓库中，uv 被收录于 README.md 的Python分类下（标记为data-lang=Python的速查条目），与 Python、pip、Conda 等文档并列，供开发者在搭建 Python 环境时快速对照查阅。

安装 uv

uv 提供"独立安装程序"与"PyPI 发布"两条安装路径，前者不依赖 Python 环境，后者便于在已有 pip 生态中顺势引入。

使用独立安装程序安装

独立安装程序会将 uv 二进制安装到用户目录，无需 sudo，也不依赖系统 Python：

macOS 或 Linux

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

Windows

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

安装完成后，uv 可执行文件会位于~/.local/bin（macOS/Linux）或对应的用户目录下；若终端无法直接找到uv命令，需要将该目录加入PATH。安装成功后可用uv --version验证版本，后续升级通过uv self update即可拉取最新版。

通过 PyPI 安装

如果系统已具备 Python 与包管理工具，也可以直接以 Python 包的形式安装：

# pip pip install uv

# pipx（隔离安装 CLI 工具，推荐） pipx install uv

使用pipx安装可以把 uv 隔离在独立环境中，避免污染全局 Python 的依赖列表。两种方式安装后的用法完全一致。

快速入门：创建新项目

创建项目

uv 用一条命令即可初始化一个结构完整的 Python 项目：

# 创建一个目录作为项目的根目录 uv init project_name

# 将当前目录作为项目的根目录 uv init

uv init project_name会新建同名目录并在其中生成项目骨架；不带参数时则直接以当前目录为根初始化。uv 也会尝试将当前 Python 版本写入.python-version，用于固定项目的解释器版本。

项目的结构

初始化完成后，项目根目录下会出现如下结构：

. ├── .venv/ # 虚拟环境目录 │ ├── bin/ # 可执行文件 │ ├── lib/ # 安装的库 │ └── pyvenv.cfg # 虚拟环境配置 ├── .python-version # 指定 Python 版本 ├── README.md # 项目说明文档 ├── main.py # 主程序入口 ├── pyproject.toml # 项目配置与依赖声明 └── uv.lock # 依赖锁定文件（自动生成）

各文件/目录的职责如下：

其中pyproject.toml是 uv 工作的枢纽，初始化后的骨架大致如下：

[project] name = "project_name" version = "0.1.0" description = "Add your description here" readme = "README.md" requires-python = ">=3.12" dependencies = []

首次执行uv add或uv run时，uv 会按.python-version/requires-python自动创建.venv，无需手动执行python -m venv。

管理项目依赖

uv 将依赖的"声明、安装、锁定、更新"统一收敛到uv add/uv remove/uv lock三个命令上，全部基于pyproject.toml+uv.lock驱动。

添加依赖

uv add requests

执行后 uv 会解析依赖树，把requests写入pyproject.toml的dependencies列表，安装到.venv，并将精确解析结果写入uv.lock。

指定依赖版本或替代来源

# 指定版本 uv add 'requests==2.28.1'

# 指定来源 uv add git+https://github.com/psf/requests

版本约束支持==、>=、~=等 PEP 440 语法，建议用单引号包裹以免 shell 对==、>等符号做特殊解释；
来源可以是指向 Git 仓库的 URL（如git+https://...），也可以配合--rev、--tag等参数固定具体提交或标签，适用于尚未发布到 PyPI 的内部依赖。

从 requirements.txt 迁移

uv add -r requirements.txt

-r会把requirements.txt中已有的依赖逐条导入pyproject.toml并完成解析锁定，是存量 pip 项目切换到 uv 时的标准迁移入口。迁移完成后即可删除requirements.txt，改由uv.lock承担可复现安装职责。

删除一个包

uv remove requests

从项目依赖中移除指定包，同时更新pyproject.toml与uv.lock。若想删除后同步生效的虚拟环境，可在其后执行uv sync。

升级一个包

uv lock --upgrade-package requests

只针对requests重新解析并升级，其他依赖的锁定版本保持不变；uv lock --upgrade则可一次性升级全部依赖。升级后运行uv sync即可将新版本安装进虚拟环境。uv.lock是最终可复现的安装依据，团队成员拉取代码后执行uv sync，即可得到与提交者完全一致的依赖环境。

运行脚本

uv run是 uv 的日常入口：它会在首次运行时自动创建并同步虚拟环境，随后在项目环境中执行目标命令。

指定脚本运行：

uv run main.py

指定 Python 版本运行：

uv run --python 3.10 main.py

不带--python时，uv 遵循.python-version与pyproject.toml中的requires-python选择解释器；
--python 3.10可临时指定版本，若本机未安装对应解释器，uv 会自动下载所需版本，无需手动管理。

uv run也可以直接运行项目内已安装的命令行工具（如uv run pytest），并保证其运行在与项目依赖一致的虚拟环境中。

构建项目

uv build

构建结果存储在dist目录下，默认同时产出 wheel（.whl）与源码包（sdist，.tar.gz）两种分发格式；若只需其一，可用--wheel或--sdist参数单独构建。构建前请确保pyproject.toml的[build-system]与[project]元信息完整，uv 会调用其中声明的后端完成打包。

延伸：uv 命令体系速览

除上述核心命令外，uv 还提供一组与既有工具链平行的子命令，便于逐步替换传统工作流：

从源码结构看，uv 的命令被设计为"项目级（init/add/run/build）"与"环境级（venv/pip/python/tool）"两大体系，前者围绕pyproject.toml组织项目生命周期，后者提供与 pip / pipx / pyenv 对等的底层能力，开发者可以按需混用、渐进迁移。

在 reference 仓库中的定位

本文是当前仓库技术速查清单（Cheat Sheets）体系中的一篇，收录于 docs/uv.md，并在 README.md 的 Python 分类中与 pip、Conda 等条目并列。阅读时可与之对照：pip备忘清单侧重于传统pip命令的逐条速查（安装、版本控制、依赖文件、镜像源），本文则聚焦 uv 以pyproject.toml为核心的现代项目管理流程；两者分别覆盖"既有环境的命令行操作"与"新项目的声明式管理"两种场景。若需要进一步了解pyproject.toml中各字段的细节，可参考 package.json.md 所体现的项目元信息管理思路。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析