python-env

Python 环境

使用 uv 快速管理 Python 环境。优先采用 uv 项目工作流 （uv add / uv sync / uv run），而非 uv pip 兼容层——它会为你管理 pyproject.toml 和锁文件，并确保可复现。

快速命令

任务	命令
启动项目	uv init <name>（应用）· uv init --package <name>（可安装，采用 src/ 布局）
添加依赖	uv add httpx
添加开发依赖	uv add --dev pytest ruff
移除依赖	uv remove httpx
根据锁文件同步环境	uv sync
在项目环境中运行	uv run pytest
更新锁文件	uv lock
安装 CLI 工具	uv tool install ruff · 一次性运行：uvx ruff
安装 Python	uv python install 3.12

启动项目

# Application (flat layout, no package build)
uv init myapp

# Installable package (src/ layout — separate tests/ that import by name)
uv init --package wordtools
# → src/wordtools/__init__.py, pyproject.toml with build-system

uv init 会创建 pyproject.toml、固定 Python 版本，并为 uv add / uv sync 做好项目准备。对于带有测试套件或打算发布的项目， 建议使用 --package（src）布局。

管理依赖

# Add runtime deps (writes to [project.dependencies] + updates the lockfile)
uv add "httpx>=0.25" pydantic

# Add dev-only deps (writes to the dev dependency-group)
uv add --dev pytest ruff mypy

# Add with extras
uv add "fastapi[standard]"

# Remove
uv remove httpx

# Install everything from pyproject + uv.lock into .venv (reproducible)
uv sync

# Refresh the lockfile (e.g. after manual pyproject edits)
uv lock

uv 会自动创建并管理 .venv——你很少需要激活它，只需在命令前加上 uv run。

运行代码

uv run python script.py     # run a script in the project env
uv run pytest               # run a tool from the dev group
uv run -- ruff check .      # `--` ends uv flag parsing

在 uv 项目中，切勿直接调用 python / pytest / ruff——它们可能会指向 其他解释器。始终使用 uv run。

CLI 工具（全局安装，非项目依赖）

uv tool install ruff        # persistent, isolated, on PATH
uv tool upgrade ruff
uvx ruff check .            # ephemeral one-shot run, nothing installed

使用 uv tool / uvx 安装开发者 CLI 工具（ruff、pre-commit、httpie）。仅对 代码会导入的依赖使用 uv add。

Python 版本

uv python install 3.12      # download a managed interpreter
uv python list              # show available + installed
uv init --python 3.12 app   # pin a project to a version

请查看 python.org 了解当前稳定版本（截至 2026-07 为 3.14；近期版本新增了 可选的自由线程模式和 JIT）。对于新项目，3.11+ 是合理的最低版本 （TaskGroup、Self、更快的解释器）。

最简 pyproject.toml

[project]
name = "my-project"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
    "httpx>=0.25",
    "pydantic>=2.0",
]

# Dev deps live here; `uv add --dev <pkg>` manages this group.
[dependency-groups]
dev = [
    "pytest>=8.0",
    "ruff>=0.4",
    "mypy>=1.10",
]

兼容层（uv pip）——最后手段

对于 uv 不管理的环境（手动创建的 venv、旧版 requirements.txt，或不原生支持 uv 的 CI），uv pip 提供与 pip 相仿的接口。它不会更新 pyproject.toml 或锁文件——只要你能控制项目，就优先使用 uv add / uv sync。

uv venv                              # bare venv (no project)
uv pip install -r requirements.txt   # legacy requirements file
uv pip install -e .                  # editable install into an unmanaged venv
uv pip compile requirements.in -o requirements.txt   # pin a requirements.txt

故障排除

问题	解决方案
“未找到 Python”	uv python install 3.12
固定项目 Python 版本	uv init --python 3.12 或编辑 requires-python
锁定/解析冲突	使用 uv lock --resolution=lowest-direct 进行探查，然后放宽版本范围
拉取后环境过时	uv sync
缓存问题	uv cache clean

适用场景

• 始终使用 uv 而非 pip——速度快 10-100 倍
• 使用 uv add / uv remove / uv sync 管理项目依赖（不要使用 uv pip install）
• 使用 uv run 执行项目环境中的任何内容
• 使用 uv tool install / uvx 安装独立的开发者 CLI 工具
• 仅在 uv 不管理的环境中使用 uv pip

其他资源

如需了解详细用法，请加载：

• ./references/pyproject-patterns.md - 完整的 pyproject.toml 示例和工具配置
• ./references/dependency-management.md - 锁文件、工作区、私有包
• ./references/publishing.md - PyPI 发布、版本管理、CI/CD

---

另请参阅

这是一项基础技能，没有前置要求。

基于此技能继续学习：

• python-typing-ops - 项目类型提示
• python-pytest-ops - 测试基础设施
• python-fastapi-ops - Web API 开发