uv

uv（Python）

当仓库包含 uv.lock、在文档或 Makefile 中提到 uv，或已使用由 uv 创建的 .venv 时，默认使用 uv 管理 Python 依赖和环境。

快速判断规则

• 如果仓库包含 uv.lock 和 pyproject.toml：将其视为由 uv 管理的项目。
• 如果仓库只有 requirements.txt：仍可使用 uv pip 快速安装。
• 优先使用项目命令（uv add/remove/sync/run/lock），而非直接使用 pip，除非仓库明确使用 uv pip。

安装（如有需要）

如有可用的打包安装方式，优先使用。如果使用官方安装程序，请先检查它（避免不加审查地直接将内容通过管道传入 shell），并遵循官方文档中的最新说明。

# macOS/Linux (official installer)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell, official installer)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

常见操作

初始化新项目

uv init
# or
uv init my-project

创建 / 使用虚拟环境

uv venv  # creates .venv

# If you need a specific version, match the project's declared requirement
# (e.g., pyproject.toml / CI config), not an arbitrary latest version.
uv venv --python 3.x

# optional activation (not required for uv commands)
source .venv/bin/activate  # macOS/Linux
# .venv\\Scripts\\activate   # Windows

添加 / 移除依赖项（更新 pyproject.toml 和 uv.lock）

uv add requests
uv add 'requests==2.31.0'
uv add -r requirements.txt

uv remove requests

锁定依赖并同步（确保安装可复现）

uv lock   # (re)generate uv.lock
uv sync   # create/update .venv to match uv.lock

如果拉取了新更改，且 uv.lock 已更改，请运行 uv sync。

在项目环境中运行命令

uv run python -m pytest -q
uv run python main.py
uv run ruff check .

使用 uv 快速替代 pip（requirements 工作流）

uv venv
uv pip install -r requirements.txt
uv pip freeze
uv pip list

注意事项 / 易踩坑

• uv 通常会自动检测并使用项目根目录中的 .venv。
• 在 CI / 容器中，你可能会看到 uv pip install --system，但本地开发时优先使用虚拟环境。
• 如果某条命令会修改依赖项，优先使用 uv add/remove/lock/sync，以确保 uv.lock 保持正确。