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
    
  
  
• 总结
  

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

1. uv --version / uv -V

• 用途：查看 uv 安装版本
  
• 示例：
  1. uv --version# 输出示例：uv 0.4.17 (a1b2c3d 2026-02-08)

  复制代码

2. uv help [COMMAND]

• 用途：查看 uv 整体帮助，或指定命令的详细帮助
  
• 参数：[COMMAND] 可选，指定要查看帮助的子命令
  
• 示例：
  1. # 查看所有命令的帮助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 ：指定包版本（如 ==1.0.0、>=0.9.0）
    
  • --git ：从 Git 仓库安装
    
  • --editable / -e：以可编辑模式安装（本地包）
    
  • --lock：添加后立即更新锁文件
    
  
  
• 示例：
  1. # 添加基础依赖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 ：从指定 requirements.txt 安装
    
  • --sync：同步环境，卸载不在依赖列表中的包
    
  
  
• 示例：
  1. # 安装项目所有依赖（含开发依赖）uv install --dev# 按锁文件安装uv install --locked# 从指定 requirements.txt 安装uv install --requirements requirements.txt# 同步环境，清理未声明的包uv install --sync

  复制代码

3. uv remove / uv rm

• 用途：从项目/环境移除依赖包
  
• 核心参数：
  
  
  
  • --dev：移除开发依赖
    
  • --lock：移除后更新锁文件
    
  
  
• 示例：
  1. # 移除基础依赖uv remove requests# 移除开发依赖uv remove --dev pytest

  复制代码

4. uv update

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

  复制代码

5. uv show

• 用途：查看已安装/可用包的详细信息
  
• 核心参数：
  
  
  
  • --installed：仅显示已安装的包
    
  • --outdated：显示可更新的包
    
  • --json：以 JSON 格式输出
    
  
  
• 示例：
  1. # 查看 requests 包的详细信息uv show requests# 查看所有已安装的包uv show --installed# 查看可更新的包uv show --outdated

  复制代码

6. uv search

• 用途：从 PyPI 搜索包
  
• 核心参数：
  
  
  
  • --limit ：限制搜索结果数量（默认 10）
    
  • --json：JSON 格式输出
    
  
  
• 示例：
  1. # 搜索 requests 相关包uv search requests# 限制搜索结果为 5 条uv search requests --limit 5

  复制代码

7. uv pip

• 用途：兼容 pip 命令（无缝替换 pip，参数与 pip 一致）
  
• 核心场景：临时使用 pip 兼容语法执行操作
  
• 示例：
  1. # 等同于 pip install requestsuv pip install requests# 等同于 pip listuv pip list# 等同于 pip show requestsuv pip show requests

  复制代码

三、环境管理命令

1. uv venv create

• 用途：创建新的虚拟环境
  
• 核心参数：
  
  
  
  • --python ：指定 Python 版本（如 3.10、3.11.4）
    
  • --name ：为环境命名（默认自动生成）
    
  • --path ：指定环境保存路径
    
  
  
• 示例：
  1. # 创建默认 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 ：激活指定名称的环境
    
  • --path ：激活指定路径的环境
    
  
  
• 示例：
  1. # 激活命名环境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 版本、路径、创建时间）
    
  
  
• 示例：
  1. # 简单列出环境uv venv list# 显示详细信息uv venv list --details

  复制代码

4. uv venv remove / uv venv rm

• 用途：删除虚拟环境
  
• 核心参数：
  
  
  
  • --name ：删除指定名称的环境
    
  • --path ：删除指定路径的环境
    
  • --all：删除所有环境（需确认）
    
  
  
• 示例：
  1. # 删除命名环境uv venv rm my-env# 删除指定路径的环境uv venv rm --path ~/envs/my-env# 删除所有环境（谨慎使用）uv venv rm --all

  复制代码

5. uv venv info

• 用途：查看当前/指定环境的信息（Python 版本、路径、依赖等）
  
• 核心参数：
  
  
  
  • --name ：查看指定名称环境的信息
    
  • --path ：查看指定路径环境的信息
    
  
  
• 示例：
  1. # 查看当前激活环境的信息uv venv info# 查看指定环境的信息uv venv info --name my-env

  复制代码

四、项目管理命令

1. uv init

• 用途：初始化新的 Python 项目（生成 pyproject.toml 等文件）
  
• 核心参数：
  
  
  
  • --name ：指定项目名称
    
  • --python ：指定项目默认 Python 版本
    
  • --license ：指定许可证（如 MIT、Apache-2.0）
    
  • --no-virtual-env：不自动创建虚拟环境
    
  
  
• 示例：
  1. # 基础初始化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 ：为指定 Python 版本生成锁文件
    
  • --upgrade：更新锁文件中的所有依赖版本
    
  
  
• 示例：
  1. # 生成基础锁文件uv lock# 包含开发依赖并更新版本uv lock --dev --upgrade

  复制代码

3. uv export

• 用途：将项目依赖导出为 requirements.txt 格式
  
• 核心参数：
  
  
  
  • --dev：包含开发依赖
    
  • --locked：按锁文件版本导出
    
  • --output ：指定导出文件路径
    
  
  
• 示例：
  1. # 导出生产依赖到 requirements.txtuv export --output requirements.txt# 导出含开发依赖的锁文件版本uv export --dev --locked --output requirements-dev.txt

  复制代码

4. uv build

• 用途：构建 Python 包（生成 wheel/sdist 包）
  
• 核心参数：
  
  
  
  • --wheel：仅生成 wheel 包
    
  • --sdist：仅生成源码包
    
  • --outdir ：指定输出目录（默认 dist/）
    
  • --no-isolation：不使用隔离环境构建
    
  
  
• 示例：
  1. # 构建 wheel 和 sdist 包uv build# 仅生成 wheel 包并指定输出目录uv build --wheel --outdir ./packages

  复制代码

5. uv publish

• 用途：发布 Python 包到 PyPI 或私有仓库
  
• 核心参数：
  
  
  
  • --repository ：指定发布的仓库（需提前配置）
    
  • --username ：仓库用户名
    
  • --password ：仓库密码/令牌
    
  • --dry-run：预览发布，不实际上传
    
  
  
• 示例：
  1. # 发布到 PyPI（需提前配置凭证）uv publish# 预览发布uv publish --dry-run# 发布到私有仓库uv publish --repository my-private-repo

  复制代码

五、配置相关命令

1. uv config get

• 用途：查看 uv 的配置项
  
• 核心参数：
  
  
  
  • ：可选，指定要查看的配置键（如 python.default-version）
    
  • --global：查看全局配置（而非项目本地配置）
    
  • --json：JSON 格式输出
    
  
  
• 示例：
  1. # 查看所有配置uv config get# 查看默认 Python 版本配置uv config get python.default-version# 查看全局配置uv config get --global

  复制代码

2. uv config set

• 用途：设置 uv 的配置项
  
• 核心参数：
  
  
  
  • ：配置键和值
    
  • --global：设置全局配置
    
  • --project：设置项目本地配置（默认）
    
  
  
• 示例：
  1. # 设置项目默认 Python 版本为 3.11uv 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

• 用途：清空指定的配置项
  
• 核心参数：
  
  
  
  • ：要清空的配置键
    
  • --global：清空全局配置
    
  
  
• 示例：
  1. # 清空项目默认 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：预览清理内容，不实际删除
    
  
  
• 示例：
  1. # 清理所有缓存uv cache clean --all# 仅清理包缓存uv cache clean --packages# 预览清理uv cache clean --dry-run

  复制代码

2. uv cache list

• 用途：列出缓存内容（包、环境等）
  
• 核心参数：
  
  
  
  • --packages：仅列出包缓存
    
  • --size：显示缓存大小
    
  • --json：JSON 格式输出
    
  
  
• 示例：
  1. # 列出所有缓存uv cache list# 列出包缓存并显示大小uv cache list --packages --size

  复制代码

七、高级/其他命令

1. uv run

• 用途：在项目/环境中运行 Python 脚本/命令
  
• 核心参数：
  
  
  
  • --python ：指定运行的 Python 版本
    
  • --no-install：不自动安装缺失的依赖
    
  
  
• 示例：
  1. # 运行 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 格式输出
    
  
  
• 示例：
  1. # 基础检查uv check# 检查开发依赖并扫描安全漏洞uv check --dev --security

  复制代码

3. uv fix

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

  复制代码

4. uv completions

• 用途：生成 uv 的终端补全脚本（支持 bash/zsh/fish 等）
  
• 核心参数：
  
  
  
  • ：指定终端类型（bash/zsh/fish/powershell）
    
  
  
• 示例：
  1. # 生成 zsh 补全脚本uv completions zsh# 生成并安装 bash 补全脚本（Linux/macOS）uv completions bash > /etc/bash_completion.d/uv

  复制代码

5. uv self update

• 用途：更新 uv 自身到最新版本
  
• 核心参数：
  
  
  
  • --version ：指定更新到的版本
    
  • --dry-run：预览更新，不实际执行
    
  
  
• 示例：
  1. # 更新到最新版本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 可快速在环境中执行脚本。
  

来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！

这个好，看起来很实用

分享、互助 让互联网精神温暖你我