Prioritize uv

核心用法

uv-priority 是一项强制性编码规范技能，要求在所有 Python 相关任务中优先使用 uv 而非 pip。核心操作模式为：

• 执行任何 Python 命令前必须包装 `uv run`：包括 python、python3、dbt、pytest、black、ruff、mypy 等所有 Python CLI 工具
• 安装依赖时必须使用 `uv add` 或 `uv pip install`：彻底替代 pip install
• 虚拟环境管理使用 `uv venv`：替代 python -m venv

典型命令映射

| 传统命令 | uv 替代方案 |

|---------|-----------|

| `python script.py` | `uv run python script.py` |

| `pip install pandas` | `uv add pandas` |

| `dbt run` | `uv run dbt run` |

| `pytest tests/` | `uv run pytest tests/` |

显著优点

1. 极速依赖解析：uv 采用 Rust 编写，解析速度比 pip 快 10-100 倍，显著缩短 CI/CD 和本地开发等待时间
2. 全局缓存共享：跨项目复用已下载包，减少磁盘占用和网络流量
3. 确定性锁定：uv.lock 文件确保团队环境完全一致，消除"在我机器上能跑"问题
4. 无缝兼容：支持 requirements.txt 和 pyproject.toml，迁移成本低
5. 统一工具链：集成虚拟环境、包管理、Python 版本管理于一体，减少工具碎片化

潜在缺点与局限性

• 生态成熟度：uv 相对较新，某些边缘场景（如特定平台二进制 wheel、私有仓库认证）可能存在兼容性问题
• 学习曲线：团队成员需适应新的命令习惯，短期内可能增加认知负担
• IDE 集成：部分 IDE 对 uv 的自动检测和集成支持不如 pip 完善，可能需要手动配置
• 锁定文件冲突：多人协作时 uv.lock 合并冲突需手动处理

适合人群

• 追求构建速度的 Python 开发团队
• 使用 dbt、FastAPI、Django、数据科学栈（pandas/numpy）的项目
• CI/CD 流水线中频繁安装依赖的场景
• 希望统一工具链、减少 pip + virtualenv + pip-tools 多工具组合复杂度的团队

常规风险

• 强制执行风险：always: true 配置意味着无法临时绕过，若 uv 未安装或故障将导致任务失败
• 环境隔离误用：错误使用 uv pip install（系统级）vs uv add（项目级）可能导致依赖污染
• 跨平台差异：Windows 与 Unix-like 系统在某些路径处理和行为上可能存在细微差异
• 依赖解析行为差异：uv 的解析器与 pip 略有不同，极少数情况下可能产生不同依赖树，需充分测试