uv 工具核心操作总结文档

一、前置准备：pipx 安装与管理 uv

uv 推荐通过 pipx 进行安装和管理，可实现独立环境隔离，避免污染全局 Python 环境。

1. 安装 pipx

操作系统	安装命令
Windows	`py -m pip install --user pipx` `py -m pipx ensurepath`
macOS & Linux	`brew install pipx`（或 `apt install pipx`） `pipx ensurepath`

2. 核心 pipx 操作（针对 uv）

bash 复制代码

# 安装 uv
pipx install uv

# 更新 uv 自身（优先推荐）
uv self update

# 无法自更新时，通过 pipx 升级
pipx upgrade uv

# 一键重装（适用于升级 Python 或环境异常时）
pipx reinstall-all

⚠️ 注意：执行 ensurepath 添加环境变量后，需重启终端和 IDE 才能使配置生效。

二、uv 核心操作指南

1. 依赖包管理（添加/分组）

1.1 基础添加语法

支持确切版本、兼容版本、可选依赖等多种指定方式，版本约束语法兼容 Python 包管理通用规范。

bash 复制代码

# 1. 添加确切版本依赖
uv add --group android uiautomator2==3.2.9

# 2. 添加兼容版本依赖（>=1.0, <2.0），等价于 uv add assertpy==1.*
uv add assertpy~=1.0

# 3. 添加带可选功能的依赖
uv add httpx[http2]==0.28.1

1.2 依赖分组最佳实践

使用 --group 为依赖分组（支持嵌套），提升部署效率，暂不推荐使用 --optional 添加可选依赖；
--dev 为特殊分组，专门存放 ruff、pylint 等本地开发/调试依赖；
重要依赖（如 uiautomator、facebook-wda，更新不遵循语义化版本）优先使用确切版本；
普通依赖（如 assertpy、backoff）仅做大版本约束，便于后续升级减少技术债（依赖 lock 文件保障部署速度）。

2. 虚拟环境（venv）相关操作

2.1 创建虚拟环境

bash 复制代码

# 默认创建（生成 .venv 目录）
uv venv

# 指定 Python 版本/路径创建（支持 uv python list 列出的版本号，或 Python 可执行文件绝对路径）
uv venv --python <PYTHON_VERSION/PYTHON_PATH>

2.2 环境同步（核心用于部署/环境还原）

bash 复制代码

# 本地默认同步（受 default-groups 配置影响，不包含所有分组）
uv sync

# 强制同步所有分组依赖
uv sync --all-groups

# 同步时保留已移除的包（默认自动删除无用包）
uv sync --inexact

# Jenkins 一键完全部署（无开发依赖、冻结版本，可结合具体分组进一步优化）
uv sync --no-dev --frozen

2.3 删除虚拟环境

uv 不提供专门的删除命令，直接通过文件操作删除即可：

bash 复制代码

# Windows/Linux/macOS 通用（删除 .venv 目录）
rm -r .venv

3. 依赖版本锁定（lock）与升级

3.1 仅更新 lock 文件（不安装到 venv）

bash 复制代码

# 全局升级所有依赖的可行版本（仅更新 lock 文件）
uv lock --upgrade

# 单独升级指定包到特定版本（仅更新 lock 文件）
uv lock --upgrade-package <package>==<version>

示例：配置 allure-pytest~=2.15.0 时，执行命令可将 2.15.0 升级到 2.15.2（兼容大版本内更新）。

3.2 一键升级（更新 lock 文件 + 安装到 venv）

bash 复制代码

uv sync -U

4. 导出 requirements 配置

bash 复制代码

# 基础导出
uv export --format requirements.txt

# 干净版本导出（无哈希、无注释、无表头，包含所有分组包）
uv export --format requirements.txt --all-groups --no-hashes --all-packages --no-annotate --no-header

5. 其他常用操作

5.1 执行依赖包命令行工具

bash 复制代码

# 示例：执行 pytest 查看版本、执行 uiauto 工具命令
uv run pytest --version
uv run uiauto.dev version

5.2 查看 Python 环境相关信息

bash 复制代码

# 列出所有已安装的 Python 解释器
uv python list --only-installed

# 查找当前环境（venv）的 Python 解释器路径（注意：PyCharm 中运行结果可能与终端不一致）
uv python find

5.3 pip 兼容性说明

uv 默认不安装 pip，且不遵守 pip 的配置文件和环境变量；
常用兼容命令仅 uv pip list（查看已安装包）；
执行 uv run pip 会报错，禁止手动安装 pip 绕过该限制。

三、核心操作速查表

操作场景	核心命令
安装 uv	`pipx install uv`
更新 uv	`uv self update`（优先）/ `pipx upgrade uv`
添加开发依赖	`uv add --dev ruff`
本地环境同步	`uv sync`
Jenkins 部署同步	`uv sync --no-dev --frozen`
升级单个包 lock 版本	`uv lock --upgrade-package <package>==<version>`
一键升级依赖并安装	`uv sync -U`
导出干净的 requirements	`uv export --format requirements.txt --all-groups --no-hashes --all-packages --no-annotate --no-header`
执行第三方工具命令	`uv run <工具命令>`
创建虚拟环境	`uv venv`（默认）/ `uv venv --python <PYTHON_PATH>`（指定 Python）

总结

环境准备优先通过 pipx 安装 uv，保障环境隔离且便于后续更新维护；
依赖管理遵循「分组分类、重要包锁确切版本、普通包锁大版本」的原则，减少技术债；
部署场景优先使用 uv sync --no-dev --frozen，本地开发可灵活使用 uv sync/uv sync -U；
避免手动干预 uv 的 pip 兼容逻辑，遵循工具原生设计规范。