一、uv 是什么

Astral（Ruff 同团队）基于 Rust 开发，单二进制文件，一套工具直接平替：
pyenv + pip + venv + pipx + poetry + isort + flake8
主打极速依赖解析、内置Python版本管理、严格遵循PEP621标准，是目前Python新项目首选工程化工具。

二、Mac 三种安装方式（推荐顺序）

方式1：官方一键脚本（最推荐，自带自更新）

无需提前装Homebrew、Python，直接终端执行：

curl -LsSf https://astral.sh/uv/install.sh | sh

安装后关闭终端重新打开，环境变量自动写入zsh配置。
验证安装：

uv --version
uvx --version

后续升级：

uv self update

如果提示 command not found，手动补PATH：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

方式2：Homebrew 安装（brew 用户首选）

brew install uv
# 更新
brew upgrade uv

Apple Silicon M系列 brew 路径：/opt/homebrew/bin，Intel：/usr/local/bin。

方式3：pipx 隔离安装

适合不想改系统PATH的场景：

python3 -m pip install --user pipx
python3 -m pipx ensurepath
pipx install uv

三、国内镜像加速（必配，解决下载慢）

终端执行配置阿里云PyPI源：

uv pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/
# 额外加清华源备用
uv pip config set global.extra-index-url https://pypi.tuna.tsinghua.edu.cn/simple

四、核心基础用法（从0新建项目）

1. 初始化项目

# 创建项目文件夹+pyproject.toml
uv init demo-project
cd demo-project

2. 管理Python解释器（替代pyenv）

# 查看可安装版本
uv python list
# 安装指定Python版本
uv python install 3.11
# 项目锁定使用3.11
uv python pin 3.11

3. 依赖管理（核心命令）

# 安装正式依赖
uv add requests pandas

# 安装开发依赖（ruff、pytest）
uv add --dev ruff pytest

# 一键安装所有依赖并生成uv.lock锁文件、自动创建.venv虚拟环境
uv sync

# 删除依赖
uv remove requests

# 查看依赖树
uv tree

# 升级全部依赖
uv lock --upgrade
# 单独升级某个包
uv lock --upgrade-package pandas

4. 运行代码（自动调用虚拟环境）

# 直接执行py文件
uv run main.py

# 进入虚拟环境终端
source .venv/bin/activate
# 退出
deactivate

5. 全局工具安装（替代pipx）

# 全局装ruff，任意目录可用
uv tool install ruff
# 升级全局工具
uv tool upgrade ruff

五、uv + Ruff 黄金组合（一键规范+格式化）

1. 项目内安装Ruff

uv add --dev ruff

2. 项目根目录 pyproject.toml 完整配置

[project]
name = "demo-project"
version = "0.1.0"
dependencies = []
requires-python = ">=3.11"

[project.optional-dependencies]
dev = [
  "ruff>=0.6.0",
  "pytest>=7.0",
]

# Ruff 代码检查+格式化配置
[tool.ruff]
target-version = "py311"
line-length = 100
exclude = [".venv", "__pycache__", "build", "dist"]

[tool.ruff.lint]
select = [
  "E", "W", "F",   # flake8 基础规范
  "I",             # isort 导入排序
  "UP",            # pyupgrade 语法升级
  "B",             # 常见bug检测
  "C4",            # 列表推导优化
]
fix = true  # 自动修复可修正问题

[tool.ruff.format]
quote-style = "double"
indent-style = "space"
line-ending = "auto"

3. 常用Ruff指令

# 代码检查并自动修复
uv run ruff check . --fix
# 全盘格式化代码
uv run ruff format .

六、VS Code 搭配 uv 环境

1. VS Code 打开项目，左下角选择解释器
2. 选中项目内 .venv/bin/python
3. 安装 Ruff VSCode 插件，保存自动格式化+实时报错提示。

七、老项目迁移适配

1. 从 requirements.txt 迁移

uv add -r requirements.txt
uv sync

2. 从 Poetry 项目迁移

uv 可直接读取 pyproject.toml + poetry.lock

uv sync
# 生成标准uv.lock，后续完全使用uv管理

八、打包发布到PyPI

# 构建wheel+sdist包
uv build
# 上传至pypi
uv publish

九、常用高频命令速查表

功能	命令
初始化项目	uv init
安装依赖	uv add xxx
安装开发依赖	uv add --dev xxx
同步环境	uv sync
运行脚本	uv run xxx
安装Python	uv python install 3.11
锁定Python版本	uv python pin 3.11
更新uv本体	uv self update
全局安装工具	uv tool install xxx

十、常见踩坑说明

1. M系列Mac 终端权限问题：首次安装允许终端访问网络即可；
2. 切换终端（zsh/bash）：脚本会自动识别写入对应配置文件，无需手动改；
3. 不想生成.venv：执行 uv sync --no-venv 直接使用系统Python。

官方参考文档

uv 中文文档：https://uv.doczh.com/
uv 英文官网：https://docs.astral.sh/uv/

三者极简关系（Poetry / pipx / uv）

1. pipx = 只干全局工具安装这一件小事
2. Poetry = 项目管理 + 打包发库
3. uv = 同时干完 Poetry + pipx + pyenv + pip 所有功能

• 你可以用 pipx 去安装 Poetry，这是官方推荐的标准姿势；
• 但不能用 Poetry 去替代 pipx；
• 装了 uv 之后，uv tool 替代 pipx，uv sync/add 替代 Poetry，两个工具都可以不再安装。