uv 安装与配置

在之前切换电脑中的python环境时使用的是 pyenv-win 安装与配置，偶然间发现已经停更好久了，查看社区发现有了更好的替代工具 uv，官方文档：https://docs.astral.sh/uv/

1.下载二进制文件

下载地址：https://github.com/astral-sh/uv/releases

2.新建目录并放置压缩包内的二进制文件

我使用的目录是 D:\Developer\uv\bin
推荐目录结构：

D:\Developer\uv\
├─ bin\                # uv.exe 所在目录
│   └─ uv.exe
├─ python\             # uv 管理的 Python 安装目录
│   ├─ cpython-3.12.1\
│   ├─ cpython-3.11.9\
│   └─ ...
└─ tools\              # uv 安装的工具（ruff、black、pytest 等）
    ├─ ruff.exe
    ├─ black.exe
    └─ ...

3.配置环境变量

+代表添加，*代表追加

[+] UV_INSTALL_DIR => D:\Developer\uv => uv的安装目录

[+] UV_PYTHON_INSTALL_DIR => D:\Developer\uv\python => 下载/管理的 Python位置

[+] UV_TOOL_DIR => D:\Developer\uv\tools => uv 安装的 CLI 工具位置，例如集中管理 ruff / black / mypy / pytest 等，不污染 Python 解释器目录

注意追加的顺序

[*] Path => %UV_INSTALL_DIR%\bin 或者 D:\Developer\uv\bin

[*] Path => %UV_INSTALL_DIR%\tools 或者 D:\Developer\uv\tools

4.测试

1.查看安装的uv版本

uv --version

2.安装一个版本

uv python install 3.12

3.查看安装的所有python版本

uv python list

4.查看使用的python版本

python --version

5.一些设计上的点

uv 没有、也刻意不提供全局切换python的命令,uv 切换 Python 的方式只有三种：

1. 命令级指定（最常用、最安全）

2. 项目级绑定（推荐的工程做法）

3. 显式调用某个解释器路径（最低层）

而非全局切换，其在设计上已抛弃这种做法，这样做的方式有以下问题：

• Windows PATH 污染严重

• 子进程不可控

• 多项目并行时容易奔溃

uv 把“切换”这个动作，从“环境层面”提升到了“执行层面”，这是相较于 pyenv 更安全、也更现代的设计。

1.命令级切换[推荐]

uv run --python 3.12 python --version
uv run --python 2.7 python --version

uv run --python 2.7 your_script.py
uv run --python 3.12 your_script.py

2.项目级固定 Python[开发项目推荐]

cd my_project
uv python pin 3.12

会生成文件 .python-version,文件中会标注项目使用的python版本，之后运行

uv run python --version

则会输出项目使用的python版本，若需要更换重新执行pin命令即可，例如

uv python pin 2.7

3.直接调用解释器路径[推荐，但可临时使用]

D:\Developer\uv\python\cpython-2.7.18\python.exe --version
D:\Developer\uv\python\cpython-3.12.1\python.exe --version