uv 入门指南

之前尝试过 venv、pyenv、poetry 等等虚拟环境管理工具，使用之后或多或少都有一些问题。 遇到了 uv 之后，发现这个工具更加好用，所以开始将自己的项目的虚拟环境全部更换为 uv。

uv 是由 Astral 团队开发的一款现代换的 Python 虚拟环境管理与打包（packing）工具。(Astral 还有一款工具叫 ruff)

uv 相比其他的虚拟环境管理工具，有以下特点：

1. ⚡️ 安装速度快，快到 10–100 倍！
2. 🐍 可以管理 Python 版本，一件安装所有版本的 Python 解释器。
3. 🚀 可以管理虚拟环境，还可以为虚拟环境指定 Python 版本
4. 💾 强大的全局缓存，节省磁盘空间。
5. 🔩 兼容 pip、venv 等工具。

我为什么会从 poetry 更换到 uv

1. uv 出现的相对较晚，没有 poetry 那么多的历史包袱。
2. uv 速度更快（使用 rust 编写）。
3. uv 指令简洁、易用
4. 没有 poetry 那么多的 breaking change。

常用指令

$ uv -help
Commands:
  run      运行命令或脚本
  init     创建一个 python 项目
  add      添加项目依赖
  remove   移除项目依赖
  sync     更新项目环境
  lock     更新项目 lock 文件
  export   将项目的 lock 文件导出为其他格式
  tree     显示项目依赖树
  tool     运行并安装 Python 包提供的命令
  python   管理和安装 Python 版本
  pip      管理与 pip 兼容的界面管理 Python 包
  venv     创建虚拟环境
  build    将 Python 包构建为源码分发包和组件
  publish  将分发包上传到包管理平台
  cache    管理 uv 缓存
  self     管理 uv 可执行文件
  version  查看 uv 版本
  help     查看帮助命令

python 版本管理

uv python list            # 列出 Python 的可用版本
uv python install 3.13    # 安装指定版本 python 解释器
uv python pin 3.13        # 切换到指定版本解释器（uv 命令下环境生效）
uv python uninstall 3.10  # 卸载指定的版本

虚拟环境管理

新项目创建虚拟环境

uv init

同步项目依赖

uv sync

激活虚拟环境

source .venv/bin/activate   # linux
.venv\Script\activate       # windows

运行 python 代码（使用虚拟环境）

uv run main.py

添加依赖

uv add flask

删除依赖

uv remove flask

工具管理

uv 的 uv tool install 和 uvx（uv tool run 的别名）可以在隔离的虚拟环境中安装命令行工具， 速度比 pipx 更快。无需显式安装即可执行一次性命令，为开发者提供了更加便捷的工具使用方式。

a

uv tool install ruff

uvx ruff check .\main.py

修改镜像源

项目配置

pypi 添加清华源

打开项目中的 pyproject.toml 文件，在最后添加以下内容：

[[index]]
url = "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple/"
default = true

运行 uv add 命令的时候也可以指定镜像源

uv add --default-index https://pypi.tuna.tsinghua.edu.cn/simple flask

全局配置

uv 也提供了全局的配置项，可以通过环境变量 UV_DEFAULT_INDEX 配置镜像源

export UV_DEFAULT_INDEX=https://pypi.tuna.tsinghua.edu.cn/simple