之前一直使用 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 命令后最好是关闭终端再打开一下。
替代 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 项目迁移
新建项目
# 新建项目
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 --