🐍 快速定位 / 入口 >>>

• uv init
• uv add
• uv run
• uv python
• uv tool uvx：/
• uv pip

🚀 起手式：从 0 到可运行项目 >>>

• uv init --app demo：新建应用项目
• uv add httpx rich：添加运行依赖
• uv run python main.py：在项目环境里执行
• uv lock uv.lock：生成或更新
• uv sync --frozen：按锁文件还原环境

uv init --app demo
cd demo
uv add httpx rich
uv run python main.py
uv lock
uv sync --frozen

📦 Recipe：快速开一个可发布包 >>>

• uv init --package demo-lib：按包结构初始化
• uv add pydantic：加运行依赖
• uv add --dev pytest ruff：加开发依赖
• uv build：构建分发包
• uv publish：发布到 PyPI

uv init --package demo-lib
cd demo-lib
uv add pydantic
uv add --dev pytest ruff
uv run pytest
uv build

▶️ Recipe：把命令、测试、脚本都收进同一环境 >>>

• uv run python script.py：跑脚本
• uv run pytest：跑测试
• uv run ruff check .：跑代码检查
• uv run --with rich script.py：临时附带额外依赖
• uv run --python 3.12 python -V：指定解释器版本

uv run pytest
uv run ruff check .
uv run --with httpx python -c "import httpx; print(httpx.get('https://example.com').status_code)"

Recipe：只想临时执行工具，不想污染项目

• uv tool install ruff
• uv tool upgrade ruff
• uv tool list
• uvx ruff check .
• uvx --python 3.12 mypy src

uv tool install ruff
uvx pycowsay "hello"
uvx --python 3.12 mypy src

🧰 Recipe：管理 Python 版本，不再手装解释器 >>>

• uv python install 3.12：安装解释器
• uv python list：查看可用版本
• uv python find 3.11：查找指定版本
• uv python pin 3.12：当前目录固定版本
• uv venv --python 3.12：按指定解释器建环境

uv python install 3.11 3.12
uv python pin 3.12
uv venv
uv run python -V

🔁 Recipe：从 requirements.txt 迁到 uv，但别一次全重构 >>>

• uv pip install -r requirements.txt：先让旧项目跑起来
• uv pip compile requirements.in -o requirements.txt：生成锁定版本
• uv pip sync requirements.txt：同步环境
• uv add uv lock

uv venv
uv pip install -r requirements.txt
uv pip freeze > requirements.lock.txt

🧩 Recipe：CI / Docker / 团队协作的稳妥姿势 >>>

• uv sync --frozen
• UV_CACHE_DIR
• 固定 Python 版本，避免 runner 漂移
• uv sync
• uv sync --all-packages

uv sync --frozen
uv run pytest
uv run ruff check .

⚠️ 常见坑 / 决策规则 >>>

• uv run uvx
• uv sync --frozen uv.lock
• requirements.txt pyproject.toml
• 私有源通常还要补认证配置，否则“解析成功、下载失败”很常见
• 想让团队一致，优先锁 Python 版本，再锁依赖版本