@
目录

一、基础命令（版本/帮助）
- [1. uv --version / uv -V](#1. uv --version / uv -V)
- [2. uv help [COMMAND]](#2. uv help [COMMAND])
- [3. uv --help / uv -h](#3. uv --help / uv -h)
二、包管理核心命令
- [1. uv add](#1. uv add)
- [2. uv install](#2. uv install)
- [3. uv remove / uv rm](#3. uv remove / uv rm)
- [4. uv update](#4. uv update)
- [5. uv show](#5. uv show)
- [6. uv search](#6. uv search)
- [7. uv pip](#7. uv pip)
三、环境管理命令
- [1. uv venv create](#1. uv venv create)
- [2. uv venv activate](#2. uv venv activate)
- [3. uv env list / uv env ls](#3. uv env list / uv env ls)
- [4. uv venv remove / uv venv rm](#4. uv venv remove / uv venv rm)
- [5. uv venv info](#5. uv venv info)
四、项目管理命令
- [1. uv init](#1. uv init)
- [2. uv lock](#2. uv lock)
- [3. uv export](#3. uv export)
- [4. uv build](#4. uv build)
- [5. uv publish](#5. uv publish)
五、配置相关命令
- [1. uv config get](#1. uv config get)
- [2. uv config set](#2. uv config set)
- [3. uv config unset](#3. uv config unset)
- [4. uv config list](#4. uv config list)
六、缓存与清理命令
- [1. uv cache clean](#1. uv cache clean)
- [2. uv cache list](#2. uv cache list)
七、高级/其他命令
- [1. uv run](#1. uv run)
- [2. uv check](#2. uv check)
- [3. uv fix](#3. uv fix)
- [4. uv completions](#4. uv completions)
- [5. uv self update](#5. uv self update)
- [6. uv self uninstall](#6. uv self uninstall)
总结

一、基础命令（版本/帮助）

1. uv --version / uv -V

用途：查看 uv 安装版本

示例：

bash 复制代码

uv --version
# 输出示例：uv 0.4.17 (a1b2c3d 2026-02-08)

2. uv help [COMMAND]

用途：查看 uv 整体帮助，或指定命令的详细帮助
参数：[COMMAND] 可选，指定要查看帮助的子命令

示例：

bash 复制代码

# 查看所有命令的帮助
uv help
# 查看 uv add 命令的详细帮助
uv help add

3. uv --help / uv -h

用途：快速查看 uv 核心帮助（同 uv help）
示例：uv -h

二、包管理核心命令

1. uv add

用途：向项目/环境添加依赖包
核心参数 ：
- --dev：添加为开发依赖（对应 pyproject.toml 的 [tool.uv.dev-dependencies]）
- --version <VERSION>：指定包版本（如 ==1.0.0、>=0.9.0）
- --git <URL>：从 Git 仓库安装
- --editable / -e：以可编辑模式安装（本地包）
- --lock：添加后立即更新锁文件

示例：

bash 复制代码

# 添加基础依赖
uv add requests
# 添加指定版本的依赖
uv add requests==2.31.0
# 添加开发依赖
uv add --dev pytest
# 从 Git 仓库安装
uv add --git https://github.com/psf/requests.git requests
# 可编辑模式安装本地包
uv add -e ./my-package

2. uv install

用途：安装项目/环境的依赖（基于 pyproject.toml 或 requirements.txt）
核心参数 ：
- --dev：同时安装开发依赖
- --locked：严格按照锁文件版本安装（忽略 pyproject.toml 版本约束）
- --no-cache：不使用缓存，强制重新下载
- --requirements <FILE>：从指定 requirements.txt 安装
- --sync：同步环境，卸载不在依赖列表中的包

示例：

bash 复制代码

# 安装项目所有依赖（含开发依赖）
uv install --dev
# 按锁文件安装
uv install --locked
# 从指定 requirements.txt 安装
uv install --requirements requirements.txt
# 同步环境，清理未声明的包
uv install --sync

3. uv remove / uv rm

用途：从项目/环境移除依赖包
核心参数 ：
- --dev：移除开发依赖
- --lock：移除后更新锁文件

示例：

bash 复制代码

# 移除基础依赖
uv remove requests
# 移除开发依赖
uv remove --dev pytest

4. uv update

用途：更新已安装的依赖包
核心参数 ：
- --dev：同时更新开发依赖
- --all：更新所有依赖（不指定包名时生效）
- --latest：更新到最新可用版本（突破版本约束）
- --dry-run：仅预览更新，不实际执行

示例：

bash 复制代码

# 更新指定包
uv update requests
# 更新所有依赖（含开发依赖）
uv update --all --dev
# 预览更新（不实际修改）
uv update --all --dry-run

5. uv show

用途：查看已安装/可用包的详细信息
核心参数 ：
- --installed：仅显示已安装的包
- --outdated：显示可更新的包
- --json：以 JSON 格式输出

示例：

bash 复制代码

# 查看 requests 包的详细信息
uv show requests
# 查看所有已安装的包
uv show --installed
# 查看可更新的包
uv show --outdated

6. uv search

用途：从 PyPI 搜索包
核心参数 ：
- --limit <NUM>：限制搜索结果数量（默认 10）
- --json：JSON 格式输出

示例：

bash 复制代码

# 搜索 requests 相关包
uv search requests
# 限制搜索结果为 5 条
uv search requests --limit 5

7. uv pip

用途：兼容 pip 命令（无缝替换 pip，参数与 pip 一致）
核心场景：临时使用 pip 兼容语法执行操作

示例：

bash 复制代码

# 等同于 pip install requests
uv pip install requests
# 等同于 pip list
uv pip list
# 等同于 pip show requests
uv pip show requests

三、环境管理命令

1. uv venv create

用途：创建新的虚拟环境
核心参数 ：
- --python <VERSION>：指定 Python 版本（如 3.10、3.11.4）
- --name <NAME>：为环境命名（默认自动生成）
- --path <PATH>：指定环境保存路径

示例：

bash 复制代码

# 创建默认 Python 版本的环境
uv venv create
# 创建指定 Python 3.10 的环境
uv venv create --python 3.10
# 命名并指定路径
uv venv create --name my-env --path ~/envs/my-env

2. uv venv activate

用途：激活虚拟环境（不同终端生效方式不同）
核心参数 ：
- --name <NAME>：激活指定名称的环境
- --path <PATH>：激活指定路径的环境

示例：

bash 复制代码

# 激活命名环境
uv venv activate my-env
# 激活指定路径的环境
uv venv activate --path ~/envs/my-env

备注：Windows 终端需用 uv env activate 后按提示执行激活脚本，Linux/macOS 可直接生效。

3. uv env list / uv env ls

用途：列出所有已创建的虚拟环境
核心参数 ：
- --json：JSON 格式输出
- --details：显示环境详细信息（Python 版本、路径、创建时间）

示例：

bash 复制代码

# 简单列出环境
uv venv list
# 显示详细信息
uv venv list --details

4. uv venv remove / uv venv rm

用途：删除虚拟环境
核心参数 ：
- --name <NAME>：删除指定名称的环境
- --path <PATH>：删除指定路径的环境
- --all：删除所有环境（需确认）

示例：

bash 复制代码

# 删除命名环境
uv venv rm my-env
# 删除指定路径的环境
uv venv rm --path ~/envs/my-env
# 删除所有环境（谨慎使用）
uv venv rm --all

5. uv venv info

用途：查看当前/指定环境的信息（Python 版本、路径、依赖等）
核心参数 ：
- --name <NAME>：查看指定名称环境的信息
- --path <PATH>：查看指定路径环境的信息

示例：

bash 复制代码

# 查看当前激活环境的信息
uv venv info
# 查看指定环境的信息
uv venv info --name my-env

四、项目管理命令

1. uv init

用途：初始化新的 Python 项目（生成 pyproject.toml 等文件）
核心参数 ：
- --name <NAME>：指定项目名称
- --python <VERSION>：指定项目默认 Python 版本
- --license <LICENSE>：指定许可证（如 MIT、Apache-2.0）
- --no-virtual-env：不自动创建虚拟环境

示例：

bash 复制代码

# 基础初始化
uv init my-project
# 指定 Python 版本和许可证
uv init my-project --python 3.11 --license MIT
# 初始化但不创建虚拟环境
uv init my-project --no-virtual-env

2. uv lock

用途：生成/更新项目的锁文件（uv.lock）
核心参数 ：
- --dev：包含开发依赖
- --python <VERSION>：为指定 Python 版本生成锁文件
- --upgrade：更新锁文件中的所有依赖版本

示例：

bash 复制代码

# 生成基础锁文件
uv lock
# 包含开发依赖并更新版本
uv lock --dev --upgrade

3. uv export

用途：将项目依赖导出为 requirements.txt 格式
核心参数 ：
- --dev：包含开发依赖
- --locked：按锁文件版本导出
- --output <FILE>：指定导出文件路径

示例：

bash 复制代码

# 导出生产依赖到 requirements.txt
uv export --output requirements.txt
# 导出含开发依赖的锁文件版本
uv export --dev --locked --output requirements-dev.txt

4. uv build

用途：构建 Python 包（生成 wheel/sdist 包）
核心参数 ：
- --wheel：仅生成 wheel 包
- --sdist：仅生成源码包
- --outdir <DIR>：指定输出目录（默认 dist/）
- --no-isolation：不使用隔离环境构建

示例：

bash 复制代码

# 构建 wheel 和 sdist 包
uv build
# 仅生成 wheel 包并指定输出目录
uv build --wheel --outdir ./packages

5. uv publish

用途：发布 Python 包到 PyPI 或私有仓库
核心参数 ：
- --repository <NAME>：指定发布的仓库（需提前配置）
- --username <USER>：仓库用户名
- --password <PASS>：仓库密码/令牌
- --dry-run：预览发布，不实际上传

示例：

bash 复制代码

# 发布到 PyPI（需提前配置凭证）
uv publish
# 预览发布
uv publish --dry-run
# 发布到私有仓库
uv publish --repository my-private-repo

五、配置相关命令

1. uv config get

用途：查看 uv 的配置项
核心参数 ：
- <KEY>：可选，指定要查看的配置键（如 python.default-version）
- --global：查看全局配置（而非项目本地配置）
- --json：JSON 格式输出

示例：

bash 复制代码

# 查看所有配置
uv config get
# 查看默认 Python 版本配置
uv config get python.default-version
# 查看全局配置
uv config get --global

2. uv config set

用途：设置 uv 的配置项
核心参数 ：
- <KEY> <VALUE>：配置键和值
- --global：设置全局配置
- --project：设置项目本地配置（默认）

示例：

bash 复制代码

# 设置项目默认 Python 版本为 3.11
uv config set python.default-version 3.11
# 设置全局 PyPI 镜像源
uv config set --global index.url https://pypi.tuna.tsinghua.edu.cn/simple

3. uv config unset

用途：清空指定的配置项
核心参数 ：
- <KEY>：要清空的配置键
- --global：清空全局配置

示例：

bash 复制代码

# 清空项目默认 Python 版本配置
uv config unset python.default-version
# 清空全局镜像源配置
uv config unset --global index.url

4. uv config list

用途：列出所有配置项（同 uv config get，仅展示键值对）
示例：uv config list --global

六、缓存与清理命令

1. uv cache clean

用途：清理 uv 的缓存（包缓存、环境缓存等）
核心参数 ：
- --all：清理所有缓存
- --packages：仅清理包缓存
- --environments：仅清理环境缓存
- --dry-run：预览清理内容，不实际删除

示例：

bash 复制代码

# 清理所有缓存
uv cache clean --all
# 仅清理包缓存
uv cache clean --packages
# 预览清理
uv cache clean --dry-run

2. uv cache list

用途：列出缓存内容（包、环境等）
核心参数 ：
- --packages：仅列出包缓存
- --size：显示缓存大小
- --json：JSON 格式输出

示例：

bash 复制代码

# 列出所有缓存
uv cache list
# 列出包缓存并显示大小
uv cache list --packages --size

七、高级/其他命令

1. uv run

用途：在项目/环境中运行 Python 脚本/命令
核心参数 ：
- --python <VERSION>：指定运行的 Python 版本
- --no-install：不自动安装缺失的依赖

示例：

bash 复制代码

# 运行 Python 脚本
uv run main.py
# 运行命令（如 pytest）
uv run pytest tests/
# 指定 Python 版本运行
uv run --python 3.10 main.py

2. uv check

用途：检查项目依赖的完整性、兼容性
核心参数 ：
- --dev：检查开发依赖
- --security：检查安全漏洞
- --json：JSON 格式输出

示例：

bash 复制代码

# 基础检查
uv check
# 检查开发依赖并扫描安全漏洞
uv check --dev --security

3. uv fix

用途：自动修复依赖问题（如版本冲突、缺失依赖）
核心参数 ：
- --dev：修复开发依赖
- --dry-run：预览修复，不实际执行

示例：

bash 复制代码

# 修复依赖问题
uv fix
# 预览修复
uv fix --dry-run

4. uv completions

用途：生成 uv 的终端补全脚本（支持 bash/zsh/fish 等）
核心参数 ：
- <SHELL>：指定终端类型（bash/zsh/fish/powershell）

示例：

bash 复制代码

# 生成 zsh 补全脚本
uv completions zsh
# 生成并安装 bash 补全脚本（Linux/macOS）
uv completions bash > /etc/bash_completion.d/uv

5. uv self update

用途：更新 uv 自身到最新版本
核心参数 ：
- --version <VERSION>：指定更新到的版本
- --dry-run：预览更新，不实际执行

示例：

bash 复制代码

# 更新到最新版本
uv self update
# 更新到指定版本
uv self update --version 0.4.17

6. uv self uninstall

用途：卸载 uv 自身
示例：uv self uninstall

总结

uv 命令核心分为基础帮助 、包管理 、环境管理 、项目管理 、配置、缓存清理 、高级操作七大模块，覆盖 Python 开发全流程；
包管理是核心，uv add/install/remove/update 对应依赖的增/装/删/更，--dev 参数可区分开发/生产依赖；
环境管理通过 uv env 系列命令完成虚拟环境的创建、激活、删除，uv run 可快速在环境中执行脚本。

UV 全命令速查手册

一、基础命令（版本/帮助）

1. uv --version / uv -V

2. uv help [COMMAND]

3. uv --help / uv -h

二、包管理核心命令

1. uv add

2. uv install

3. uv remove / uv rm

4. uv update

5. uv show

6. uv search

7. uv pip

三、环境管理命令

1. uv venv create

2. uv venv activate

3. uv env list / uv env ls

4. uv venv remove / uv venv rm

5. uv venv info

四、项目管理命令

1. uv init

2. uv lock

3. uv export

4. uv build

5. uv publish

五、配置相关命令

1. uv config get

2. uv config set

3. uv config unset

4. uv config list

六、缓存与清理命令

1. uv cache clean

2. uv cache list

七、高级/其他命令

1. uv run

2. uv check

3. uv fix

4. uv completions

5. uv self update

6. uv self uninstall

总结