findscripter uv 高速 Python 包管理
uv 是 Astral 用 Rust 写的极速 Python 包管理器（比 pip 快 10-100x），一把刀覆盖：项目初始化、依赖解析/安装、虚拟环境、Python 解释器安装、锁文件。可作为 pip / pip-tools / poetry 的替代。
何时使用
- 新建 Python 项目、快速搭脚手架（
uv init）。 - 增删/升级/锁定依赖，需要可复现构建（
uv.lock）。 - 创建管理虚拟环境、安装/固定 Python 解释器版本。
- 从 pip / pip-tools / poetry 迁移。
- 给 CI/CD 与 Docker 构建提速（全局缓存 +
--frozen）。 - monorepo 多包工作区管理。
不该用：与 Python 包管理无关；需要 conda 生态/非 Python 系统包；只想做运行时性能调优（看 python-performance-optimization）；无网且缓存为空时仍要联网解析。
步骤 / 指令
新项目标准流程：
uv init my-project && cd my-project—— 生成pyproject.toml、.python-version、README.md、.gitignore。uv python pin 3.12—— 固定 Python 版本（写入.python-version）。uv add <pkg>加生产依赖；uv add --dev pytest ruff加开发依赖。uv run <cmd>执行命令，自动建/激活 venv，无需手动 activate。- 提交
pyproject.toml与uv.lock入版本库。
接手已有项目：git clone 后 uv sync（按锁文件装齐，自动建 venv）；uv sync --all-extras 含可选组；uv lock --upgrade 升级。
关键命令速查：
- 依赖：
uv add/uv remove/uv add --upgrade <pkg>/uv sync/uv lock - 环境：
uv venv [--python 3.12]/uv run <cmd> - Python：
uv python install 3.12/uv python list/uv python pin 3.12 - pip 兼容层：
uv pip install -r requirements.txt/uv pip freeze/uv pip list - 导出/缓存：
uv export --format requirements-txt > requirements.txt/uv cache clean/uv cache dir
示例
安装与建项目：
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -ExecutionPolicy Bypass -c "irm https://astral.sh/uv/install.ps1 | iex"
uv --version
uv init my-project && cd my-project
uv python pin 3.12
uv add fastapi uvicorn pydantic
uv add --dev pytest ruff mypy
uv run pytest
带约束/来源的依赖：
uv add "django>=4.0,<5.0"
uv add git+https://github.com/user/repo.git@v1.0.0
uv add -e ./local-package # 可编辑本地包
CI（GitHub Actions）——缓存 + 冻结安装：
- uses: astral-sh/setup-uv@v2
with: { enable-cache: true }
- run: uv python install 3.12
- run: uv sync --all-extras --dev
- run: uv run pytest
Docker 多阶段构建（只拷 venv，runtime 不带 uv）：
FROM python:3.12-slim AS builder
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev --no-editable
FROM python:3.12-slim
WORKDIR /app
COPY --from=builder /app/.venv .venv
COPY . .
ENV PATH="/app/.venv/bin:$PATH"
CMD ["python", "app.py"]
monorepo 工作区（根 pyproject.toml）：
[tool.uv.workspace]
members = ["packages/*"]
注意事项
- CI/Docker 必须用
uv sync --frozen：严格按uv.lock安装、跳过解析，保证可复现；锁文件缺失会失败。 - 提交
uv.lock进版本库；用uv lock --check校验是否与pyproject.toml同步。 - 优先
uv run而非手动激活 venv，避免环境串味。 - 全局缓存默认位于 Linux
~/.cache/uv、macOS~/Library/Caches/uv、Windows%LOCALAPPDATA%\uv\cache；磁盘紧张用uv cache clean。 - 离线场景：
uv sync --frozen --offline仅从缓存装，缓存未命中会报错。 - poetry 项目可直接
uv sync（uv 读[project]）；纯[tool.poetry]旧式声明需先迁到标准[project]。 - uv 迭代很快，留意命令/标志随版本演进，遇异常先
uv --version比对官方文档。
互见
- related：
async-python-patterns—— 项目就绪后的异步并发编码模式 - related：
python-testing-pytest—— 用uv run pytest跑测试的具体写法 - combines_with：
ci-cd-pipeline-builder—— 把uv sync --frozen接入流水线 - combines_with：
docker-development-optimizer—— uv 多阶段镜像的进一步瘦身加固 - combines_with：
dependency-auditor—— 对uv.lock做依赖与供应链审计
采编自 sickn33/antigravity-awesome-skills（MIT）。