Python UV两种完整安装教程(含详细代码)_Python

前言

uv 是由 astral 公司（ruff 代码检查工具的开发者）用 rust 编写的超快速 python 包管理器和项目管理工具，速度比 pip 快 10-100 倍，可一站式替代 pip、pip-tools、virtualenv 和 pyenv 等多个工具。

一、系统要求

操作系统：windows 10+、macos 11+、linux（x86_64/arm64）
无需预先安装 python（uv 可自动下载管理 python 版本）

二、安装方法

方法一：官方独立安装脚本（推荐）

这是最推荐的安装方式，无需依赖任何现有环境，自动配置环境变量。

windows（powershell）

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

macos/linux（终端）

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

如果系统没有 curl，可以使用 wget：

wget -qo- https://astral.sh/uv/install.sh | sh

安装特定版本

# macos/linux
curl -lssf https://astral.sh/uv/0.11.2/install.sh | sh

# windows powershell
powershell -executionpolicy bypass -c "irm https://astral.sh/uv/0.11.2/install.ps1 | iex"

方法二：系统包管理器

macos（homebrew）

brew install uv

windows（winget）

winget install --id astral.uv

linux（conda）

conda install -c conda-forge uv

方法三：通过 pip 安装（已安装 python 时）

# 普通安装
pip install uv

# 推荐使用 pipx 安装到隔离环境
pipx install uv

三、验证安装

安装完成后，必须关闭并重新打开终端，然后运行以下命令验证：

uv --version
# 或
uv -v

成功输出示例：

uv 0.11.13 (4512a3931 2026-05-10 x86_64-pc-windows-msvc)

四、国内镜像加速配置（必做）

由于默认源在国外，国内用户必须配置镜像才能获得良好的下载体验。

方法一：全局环境变量配置（推荐）

windows powershell（临时生效）

$env:uv_index_url="https://pypi.tuna.tsinghua.edu.cn/simple"
$env:uv_python_download_mirror="https://mirrors.tuna.tsinghua.edu.cn/python"

macos/linux（临时生效）

export uv_index_url=https://pypi.tuna.tsinghua.edu.cn/simple
export uv_python_download_mirror=https://mirrors.tuna.tsinghua.edu.cn/python

永久生效配置

windows：右键 "此电脑"→"属性"→"高级系统设置"→"环境变量"，在用户变量中添加上述两个变量
macos/linux：将上述两行添加到 ~/.zshrc 或 ~/.bashrc 文件末尾，然后执行 source ~/.zshrc

验证配置是否生效

在新终端中运行以下命令，检查环境变量是否已加载：

# 检查包镜像配置
echo $env:uv_index_url

# 检查 python 下载镜像配置
echo $env:uv_python_download_mirror

方法二：项目级配置

在项目根目录创建 uv.toml 文件：

index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"
python-download-mirror = "https://mirrors.tuna.tsinghua.edu.cn/python"

五、基本使用入门

1. 安装 python 版本

# 安装最新稳定版 python
uv python install

# 安装指定版本
uv python install 3.12

# 查看已安装的 python 版本
uv python list

2. 创建新项目

# 初始化新项目（自动创建虚拟环境）
uv init my_project
cd my_project

# 或在现有项目中创建虚拟环境
uv venv

3. 依赖管理

# 添加依赖
uv add requests
uv add "fastapi&gt;=0.110.0"
uv add pytest --dev  # 添加开发依赖

# 删除依赖
uv remove requests

# 同步依赖（根据 pyproject.toml 和 uv.lock 安装）
uv sync

# 更新所有依赖到最新版本
uv lock --upgrade

4. 运行命令

# 在虚拟环境中运行 python 脚本
uv run python main.py

# 运行项目中的脚本
uv run script_name

六、常见问题与解决方案

问题 1：安装后提示 "command not found: uv"

原因：环境变量未生效或未正确配置。

解决方案：

关闭并重新打开终端
检查安装路径是否在 path 中：
- windows：c:\users\<你的用户名>\.local\bin
- macos/linux：~/.local/bin

手动添加到 path（临时生效）：

# macos/linux
export path=$path:~/.local/bin

# windows powershell
$env:path += ";$env:userprofile\.local\bin"

问题 2：下载速度慢或超时

解决方案：按照上文 "国内镜像加速配置" 部分配置清华源。

问题 3：权限错误