uv 替代 pyenv + pipx + poetry 环境管理实践

之前一直使用 pyenv + pipx + poetry 的组合方案管理 Python 版本和虚拟环境，最近在体验了一段时间 uv 后，逐步把所有的 Python 项目都迁到 uv 了，迁移过程也很丝滑。这篇博客文章分享一些个人在迁移至 uv 过程中总结的一些经验，希望能帮助到有这个需求的同学。

安装

安装过程就不细说了，可以参考官方文档的说明。
我的开发环境是 Windows 11 + WSL，Shell 是 zsh，👇是我安装 uv 的过程：

# 安装
wget -qO- https://astral.sh/uv/install.sh | sh

# 如果使用👆的方式安装，则用👇的命令更新
uv self update

# 命令补全
echo 'eval "$(uv generate-shell-completion zsh)"' >> ~/.zshrc
echo 'eval "$(uvx --generate-shell-completion zsh)"' >> ~/.zshrc

# 卸载
uv cache clean
rm -r "$(uv python dir)"
rm -r "$(uv tool dir)"
rm ~/.local/bin/uv ~/.local/bin/uvx

替代 pyenv

之前一直使用 pyenv 管理不同 Python 版本，uv 相应的命令如下：

# 安装 Python 3.12
uv python install 3.12

# 安装到全局环境，会将 Python 可执行程序放到 ~/.local/bin 路径下
uv python install 3.12 --preview --default

离线安装 Python

因神秘力量的干扰，uv python install 可能无法从网络上下载 Python 安装包，可以通过下面的方式离线安装：

# 先手动下载指定的 Python 安装包（这里只是示例，根据实际情况替换安装包的 URL）
wget https://github.com/astral-sh/python-build-standalone/releases/download/20250317/cpython-3.12.9%2B20250317-x86_64-unknown-linux-gnu-install_only_stripped.tar.gz

# 通过环境变量指定安装包所在路径并安装
UV_PYTHON_INSTALL_MIRROR=file:///mnt/nvme2/download uv python install 3.12

pyenv 的卸载方式：

rm -rf $(pyenv root)

执行完 rm 命令后最好是关闭终端再打开一下。

替代 pipx

pipx 通常用来安装一些 Python 开发的命令行工具，好处是隔离各个工具的执行环境。uv 对应的工具是 uv tool（大部分情况下可简写为 uvx），用法：

# 独立的环境安装 ruff，直接使用 ruff 命令
uv tool install ruff

# 增加其他依赖
uv tool install mkdocs --with mkdocs-material

# 更新安装的工具
uv tool upgrade ruff
uv tool upgrade --all

pipx 的卸载方式：

先通过 pipx uninstall xxx 删除安装的包
如果通过 pip list | grep pipx 检查到 pipx 是通过 pip 安装的，则可以直接卸载：pip uninstall pipx
~/.local/share/pipx 下可能还有一些残留，清理掉即可

替代 poetry

从 poetry 项目迁移

uvx migrate-to-uv

新建项目

# 新建项目
uv init my_project

# 或者新建项目时指定 Python 版本
uv init my_project --python 3.12

# 或者先创建项目文件再初始化
mkdir my_project
cd my_project
uv init

管理依赖

# 添加依赖
uv add requests

# 移除依赖
uv remove requests

# 更新依赖
uv lock --upgrade-package requests

克隆了 uv 管理的项目，类似于 poetry install，执行 sync 命令创建虚拟环境和安装依赖一步到位：

uv sync

# 不把当前 project 装进去
uv sync --no-install-project

导出 requirements.txt
类似于 poetry export，使用👇命令导出 requirements.txt 文件：

uv export --format requirements-txt -o requirements.txt --frozen

使用 pip

uv 不再用 pip，直接用 uv 环境中的 pip 会报错。大部分情况下应该坚持使用 uv 管理依赖，但有时候确实需要使用 pip 时，则可以用 uv pip 代替：

uv pip install -r requirements.txt

如果虚拟环境已经创建好了，希望 uv pip 将依赖装到这个虚拟环境里，则可以通过环境变量指定虚拟环境的位置：

VIRTUAL_ENV=.venv uv pip install -r requirements.txt

我需要 pip 的场景一般是使用 ansible 在服务器部署项目，这是对应的 ansible task 申明方式：

- name: Install requirements using uv pip
  ansible.builtin.command:
    chdir: "{{ proj_repo }}"
    cmd: "{{ uv }} pip install -r requirements.txt --python 3.12"
  environment:
    # https://docs.astral.sh/uv/pip/environments/#discovery-of-python-environments
    VIRTUAL_ENV: "{{ venv_path }}"

安装 ansible

uv 安装 ansible 没有 pipx 方便，主要是它不会在 ~/.local/bin 下创建 ansible 各个工具的软连接，暂时参考这个 issue 解决：

uv tool install ansible

[ -d "$(uv tool dir)/ansible/bin/" ] && find "$(uv tool dir)/ansible/bin/" -mindepth 1 -maxdepth 1 -type f -executable -regextype posix-extended -regex '^((.+/)?)[^.]+' -print0 | xargs -0 ln -s -t "${HOME}/.local/bin/"

总结

从目前的使用体验来看，uv 基本可以替代掉传统的 Python 环境管理工具了，而且速度确实嘎嘎的快，非常香！

-- EOF --