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 requests uv pip install requests # 等同于 pip list uv pip list # 等同于 pip show requests uv 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.txt uv 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.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

• 用途：清空指定的配置项
  
• 核心参数：
  
  
  
  • ：要清空的配置键
    
  • --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 可快速在环境中执行脚本。
  

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

谢谢楼主提供！

鼓励转贴优秀软件安全工具和文档！

感谢分享，学习下。