uv 完整使用指南

uv 是一个由 Astral 开发的高性能 Python 包管理和项目管理工具，旨在提供极速且统一的 Python 开发体验。它整合了 pip、poetry、pyenv 和 virtualenv 的核心功能。

1. 安装 uv

1.1 Windows 系统安装

打开 PowerShell（建议以管理员身份运行），执行以下命令：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

命令解释：

ExecutionPolicy ByPass：临时绕过脚本执行策略限制
irm：Invoke-RestMethod 的别名，用于下载安装脚本
iex：Invoke-Expression 的别名，执行下载的脚本

安装过程：

脚本会自动检测系统架构（x64/ARM64）
下载对应的 uv.exe 可执行文件
将 uv 安装到用户目录：%USERPROFILE%\.cargo\bin\
自动配置环境变量（可能需要重启终端生效）

1.2 macOS 系统安装

打开终端，执行以下命令：

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

命令解释：

curl -LsSf：静默下载并跟随重定向
安装路径：~/.cargo/bin/uv

1.3 Linux 系统安装

与 macOS 相同：

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

安装完成后，可能需要手动添加到 PATH：

export PATH="$HOME/.cargo/bin:$PATH"

建议将上述命令添加到 ~/.bashrc 或 ~/.zshrc 中。

2. 验证安装

2.1 检查 uv 是否安装成功

关闭并重新打开终端（Windows 用户可能需要重启 PowerShell），然后运行：

uv --version

预期输出示例：

uv 0.4.30 (或更高版本)

如果显示版本号，说明安装成功。

2.2 查看 uv 安装路径

Windows：

where uv

macOS / Linux：

which uv

预期输出示例：

Windows: C:\Users\你的用户名\.cargo\bin\uv.exe
macOS/Linux: /Users/你的用户名/.cargo/bin/uv

2.3 查看帮助信息

uv --help

这会显示 uv 的所有可用命令和选项，确认工具可以正常运行。

2.4 测试基本功能

创建一个测试目录并初始化项目：

mkdir uv-test
cd uv-test
uv init

预期结果：

创建 pyproject.toml 文件
创建 hello.py 示例文件
显示初始化成功的提示信息

查看生成的文件：

dir  # Windows
ls   # macOS/Linux

运行示例程序：

uv run hello.py

预期输出：

Hello from uv-test!

如果以上步骤都成功，说明 uv 已经完全安装并可以正常使用了。

3. 更新 uv

当有新版本发布时，可以使用以下命令更新：

uv self update

输出示例：

Updating uv to 0.4.31
Downloaded uv 0.4.31
Updated uv to 0.4.31

验证更新：

uv --version

4. 常见安装问题排查

4.1 Windows 环境变量未生效

如果安装后提示 uv 命令不存在：

手动检查环境变量：
- 按 Win + R，输入 sysdm.cpl，回车
- 点击"高级" → "环境变量"
- 在"用户变量"中找到 Path
- 确认是否包含：%USERPROFILE%\.cargo\bin
如果没有，手动添加该路径
重启 PowerShell 或命令提示符

4.2 macOS/Linux 权限问题

如果提示权限不足：

chmod +x ~/.cargo/bin/uv

4.3 网络问题

如果下载失败，可以尝试：

使用代理
手动下载安装包：访问 https://github.com/astral-sh/uv/releases
解压后将 uv 可执行文件放到 PATH 目录中

目录CONTENT

uv-安装与验证