uv是专为速度和正确性设计的新一代Python包解析与安装工具，命令风格类似Cargo/npm；uv install用于交互式依赖管理（读pyproject.toml、生成uv.lock并安装），uv sync则严格按现有uv.lock确定性还原环境，适用于CI/CD部署。
uv 不是 pip 的替代品，而是专为速度和正确性设计的新一代 Python 包解析与安装工具；它的命令行参数风格更接近 Cargo 或 npm，而非传统 pip —— 比如没有 --upgrade 这种模糊选项，而是用 uv add --upgrade 明确作用域。
uv install 和 uv sync 的区别在哪
uv install 是面向开发者的“交互式依赖管理”命令，会读取 pyproject.toml（或 requirements.txt），解析依赖树、写入 uv.lock，并安装到当前环境；它默认不覆盖已有 lock 文件，除非加 --locked 或 --frozen。
uv sync 则是面向 CI/CD 或部署场景的“确定性还原”命令：它严格按现有 uv.lock 安装，不重新解析、不生成新 lock，失败即报错。如果你在 GitHub Actions 里看到 uv sync 报 No lockfile found，说明你漏了 uv lock 步骤或没提交 uv.lock。
- 本地开发调试 → 用
uv install - Docker 构建或生产部署 → 用
uv sync - 想强制重算依赖 →
uv install --locked（先删 lock 再生成） - 想跳过 lock 校验直接装 →
uv install --frozen（但不推荐）
为什么 --python 参数经常不生效
--python 只控制“目标解释器版本”，不自动下载或管理 Python 本身。比如 uv install --python 3.11 会去找系统已有的 python3.11 可执行文件，找不到就报 Requested Python version not found，不会像 pyenv 那样帮你装一个。
立即学习“Python免费学习笔记（深入）”；
常见误操作：
- 以为
--python 3.12.4能触发下载 → 实际只支持3.12这种主次版本，点号后数字会被忽略 - 在 macOS 上用 Homebrew 装的 Python，路径不在
$PATH里 → uv 找不到，需显式指定--python /opt/homebrew/bin/python3.12 - Windows 上混用 conda 和 uv → conda 的 python.exe 常带 launcher wrapper，uv 可能无法正确识别其版本，建议用
--python $(where python)先确认路径
uv add 时怎么指定包来源（本地路径、git、PEP 508 URL）
uv add 支持多种包来源格式，但语法必须严格符合 PEP 508，且不能混用 pip-style 的 @ 语法（比如 requests@git+https://... 会报错）。
正确写法：
- 本地目录：
uv add ./my-package（路径必须以./或../开头） - Git 仓库：
uv add git+https://github.com/psf/requests.git@main - 带子目录的 Git：
uv add git+https://github.com/pypa/pip.git#subdirectory=src - 带版本约束的 wheel：
uv add "httpx[cli] @ https://files.pythonhosted.org/.../httpx-0.27.0-py3-none-any.whl"
注意：所有 URL 必须用双引号包裹，否则 shell 会把 [cli] 当作 glob 展开；uv add 不支持 -e（editable mode），要 editable 安装得用 uv pip install -e ./pkg。
pip 兼容命令（uv pip）有哪些坑
uv pip 是 uv 提供的 pip 兼容层，但它不是 100% 行为一致。最常踩的三个坑：
-
uv pip install --user在非虚拟环境中可能静默失败，因为 uv 默认不写用户 site-packages，需加--python-path显式指定解释器路径 -
uv pip list不显示通过uv add安装的包（因为 uv 管理的是 project-level 依赖，pip list 查的是 site-packages），要用uv tree或uv pip show xxx -
uv pip install -r requirements.txt会绕过 uv 的 resolver，直接走 pip 兼容逻辑，失去速度优势；应优先用uv install -r requirements.txt
如果你的项目同时有 pyproject.toml 和 requirements.txt，别混用 uv install 和 uv pip install —— 锁文件和实际安装状态会不一致，debug 时很难判断哪个包来自哪条路径。
