全部速查表Python开发

uv

uv 0.4+

uv CLI 命令快速参考：Python 项目初始化、依赖管理、虚拟环境、lockfile 解析、工具运行器与自更新，并附带常用参数和实操示例。

39 条命令

安装 uv

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

macOS / Linux 上的一行官方安装脚本——把 uv 装到 `~/.local/bin` 并加入当前 shell 的 PATH。

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

pipx install uv

通过 pipx 把 uv 装为隔离的 CLI 工具（在受管理的 Python 安装上推荐）。

pipx install uv

winget install --id=astral-sh.uv

通过 Windows 包管理器（Windows 10/11）安装 uv。

winget install --id=astral-sh.uv

自更新

uv self update

把 uv 更新到最新发行版。用 `--preview` 拉取下一个预发行版本。

--preview；--stable

uv self update

Python 版本

uv python install <ver>

下载一个 Python 解释器到 uv 的管理缓存（`~/.cache/uv` / `%LOCALAPPDATA%\uv`）。可传 `3.12`、`3.11.9`，甚至夜版的 `cpython-3.13.0a5`。

3.12；3.11.9；[email protected]；--mirror

uv python install 3.12

uv python list

列出 uv 可以下载的所有 Python 解释器（CPython、PyPy、free-threaded 构建）。用 `--only-installed` 只看已下载的。

--only-installed；--all-versions；--arch；--os

uv python list --only-installed

uv python find

打印 uv 在当前目录下会使用的解释器路径。会遵循 `.python-version`、`pyproject.toml` 与已激活的虚拟环境。

uv python find 3.12

uv python pin <ver>

为当前项目锁定 Python 版本——写入 `.python-version`。CI / Docker 可以读取它以匹配本地解释器。

uv python pin 3.12

项目初始化

uv init <name>

搭建一个新的 Python 项目：`pyproject.toml`、hello-world 模块、`.gitignore`，可选 tests / README。

--package 构建为可分发包；--lib 构建为库；--bare 不带源码布局；--python <ver>；--no-readme；--no-pin-python

uv init my-app --package --python 3.12

uv init --lib <name>

初始化为库项目（src 布局，支持 `from <name> import ...`）。

uv init my-lib --lib

同步

uv sync

把 `pyproject.toml` 与 `uv.lock` 中声明的依赖全部安装到项目虚拟环境。幂等；`--frozen` 跳过 lockfile 更新，`--locked` 在需要变更时失败。

--frozen；--locked；--no-dev；--extra <name>；--all-extras；--group <name>；--no-install-project

uv sync --all-extras

uv lock

解析并写出 `uv.lock` 但不安装。用 `--check` 校验它是否与 `pyproject.toml` 一致（CI 中很有用）。

--check；--upgrade；--upgrade-package <pkg>；--frozen；--dry-run

uv lock --check

添加 / 移除

uv add <pkg>

向 `pyproject.toml` 添加依赖，更新 `uv.lock`，并安装到 venv。

--dev；--group <name>；--optional <extra>；--upgrade；--<specifier>；--editable <path>；--raw；--no-sync；--python <ver>

uv add requests rich

uv add 'requests>=2.32'

添加带版本说明符（PEP 440）的依赖。建议加上 shell 引号。

uv add 'requests>=2.32,<3'

uv add --dev pytest ruff mypy

添加仅开发使用的依赖——会写到 `pyproject.toml` 的 `[dependency-groups].dev]`。

uv add --dev pytest ruff

uv add --group docs sphinx

添加到具名依赖组。可通过 `uv sync --group docs --group lint` 一次安装多个组。

uv add --group lint ruff mypy

uv remove <pkg>

从 `pyproject.toml`、lockfile 与 venv 中移除依赖。

--dev；--group <name>；--optional <extra>

uv remove requests

运行

uv run <cmd>

在项目虚拟环境中运行命令。若 venv 不存在会自动重建。

--with <pkg> 添加临时依赖；--with-requirements <file>；--no-sync；--locked；--frozen；--isolated；--refresh-package <pkg>；--package <name>

uv run python -m myapp

uv run pytest

运行安装在项目 venv 中的工具——无需先 source venv。

uv run pytest -x --cov

uv run --with requests python -c 'print(requests.__version__)'

运行一个一次性脚本并附带临时依赖，缓存后会复用。

uv run --with httpx python -c 'import httpx; print(httpx.get("https://example.com").status_code)'

uv run script.py

运行使用 PEP 723 内联元数据的脚本（uv 读取顶部的 `# /// script` 块并按需解析）。

--no-sync

uv run ./hello.py

管理 venv

uv venv

在 `.venv` 创建项目虚拟环境。用 `--seed` 同时捆绑 pip + setuptools。

<path>；--python <ver>；--seed；--no-seed；--prompt <name>；--system-site-packages；--clear；--relocatable

uv venv --python 3.12

uv venv --seed

创建 venv 同时安装 pip / setuptools / wheel——在 venv 内部仍想用 `pip install` 工作流时需要。

uv venv --seed --python 3.11

uv remove

删除项目 venv 与 lockfile。配合 `uv sync` 可重新开始。

uv remove && uv sync

运行 CLI 工具

uvx <tool>

在临时环境中运行 CLI 工具（`uv tool run` 的别名）。首次使用后会缓存。

<tool>@<ver>；--from <pkg>；--with <dep>；--upgrade；--quiet

uvx ruff check .

uvx --from 'pycowsay>=2.0' cowsay 'Hello uv!'

运行由特定包暴露的工具（当包名与 CLI 名不同时使用）。

uvx --from 'sqlfluff' sqlfluff lint models/

安装工具

uv tool install <pkg>

把全局 CLI 工具安装到隔离环境（类似 pipx）。该工具会被加入 PATH。

--python <ver>；--with <dep>；--reinstall；--quiet；--force

uv tool install ruff

uv tool list

列出所有通过 `uv tool install` 安装的 CLI 工具。

uv tool list

uv tool uninstall <pkg>

卸载通过 `uv tool install` 安装的 CLI 工具。

--quiet

uv tool uninstall ruff

uv tool upgrade

把所有已安装工具升级到最新版本（遵循 `uv tool update-self` 与 pin 文件）。传名字可指定单个工具。

<tool>；--all；--reinstall；--quiet

uv tool upgrade --all

索引 / 缓存

uv cache clean

清空 uv 的模块缓存（`~/.cache/uv`）。搭配 `uv sync --refresh` 可以强制完全重下。

<package>；--force

uv cache clean ruff

uv cache dir

打印 uv 用于缓存已下载 wheel 的目录。

uv cache dir

uv pip install <pkg>

切到 pip 兼容模式——迁移存量项目或仍有工具调用 `pip` 时很有用。

<pkg>；-r <requirements.txt>；-e <path>；--index-url <url>

uv pip install -r requirements.txt

uv pip compile <in> -o <out>

把 `requirements.in` 解析为锁定的 `requirements.txt`（类似 `pip-tools`）。

uv pip compile requirements.in -o requirements.txt --upgrade

构建 / 发布

uv build

为项目构建 sdist 与 wheel（按 `pyproject.toml` 使用 hatchling / setuptools / poetry core 等插件）。

-o <dir>；--wheel；--sdist；--no-byte-compile

uv build

uv publish

把构建好的制品上传到 PyPI（或通过 `--index` 指向自定义索引）。

--token <pypi-token>；--index <name>；--publish-url <url>；--trusted-publishing <on|off>

uv publish --token $PYPI_TOKEN

诊断

uv --version

打印 uv 版本。

uv --version

uv help

列出所有 uv 子命令。

uv help

uv help <subcommand>

为单个子命令打印完整参数列表。

uv help sync

商标与使用声明

本批命令行工具速查手册为开源社区参考资料。文中涉及的各工具的名称、标识、商标（如 Git™、Docker™、Kubernetes®、kubectl、PostgreSQL®、MySQL®、Redis™、MongoDB®、Linux™、PowerShell™、Vim™ 等）均归对应权利人所有，此处仅为识别与参考之目的使用。

本速查手册的全部内容均为独立编写的简化自包含参考，**与任何官方文档不存在隶属、被认可或引用关系**。命令列表、参数说明、示例均为作者原创简化表达；如需权威信息，请参阅各工具的官方文档。

命令语法与参数可能在不同工具版本中有所差异。所示版本标签对应稳定发布版本；其他版本行为可能有所不同。本速查手册**不代表**商标权利人的任何偏好或推荐。

如商标或版权方认为本站部分内容存在权益侵害，请发送邮件至[email protected]，我们在收到有效权属证明后，会在合理期限内修改或移除相关内容。

本网站不对因使用本站信息而产生的任何直接或间接损失承担法律责任。

关于 uv

uv 是一款极为快速的 Python 包与项目管理器，由 Astral（ruff 与 Python 类型检查器 ty 背后的团队）使用 Rust 编写，2024 年首次发布，目标是用一个二进制取代 pip、pip-tools、pipx、pyenv、virtualenv 以及部分 Poetry / pdm 功能。凭借并行下载与全局模块缓存（`~/.cache/uv`），安装速度比 pip 快 10-100 倍。uv 支持标准 `pyproject.toml`（PEP 621）以及更新的 PEP 723 内联脚本元数据（单文件脚本自带声明的依赖）。它在 macOS、Linux、Windows 上都能运行，并发布为单一约 30 MB 的二进制（homebrew / pipx-installer / curl-install.sh / winget）。uv 不会上传你的代码到任何地方——它只与配置的 Python 包索引（`--index-url`，默认 PyPI）通信。

速查页版本 1.0.0

uv