uv 虚拟环境管理工具使用笔记（Python 开发必备）

一、uv 基础介绍与安装

1. uv 是什么

uv 是一个高性能的 Python 虚拟环境和依赖管理工具，由 Astral 公司开发（Ruff 同团队），相比传统的 venv/pipenv/poetry，具有极快的依赖解析速度和简洁的命令行体验，支持虚拟环境创建、依赖安装/更新/卸载、pyproject.toml 管理等核心功能。

2. uv 安装方法

方法1：官方一键安装（推荐，跨平台）

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

方法2：pip 安装（需已安装 Python）

pip install uv

方法3：Windows 手动安装（PowerShell）

iwr -useb https://astral.sh/uv/install.ps1 | iex

验证安装

uv --version  # 输出版本号则安装成功

二、uv 核心操作（虚拟环境管理）

1. 虚拟环境创建

基础创建（默认 Python 版本）

# 在当前目录创建虚拟环境（默认生成 .venv 文件夹）
uv venv

指定 Python 版本创建

# 指定版本（如 3.11），uv 会自动下载对应版本（无需提前安装）
uv venv --python 3.11

# 指定虚拟环境存放路径
uv venv ./my-venv  # 环境文件存放在 my-venv 文件夹

2. 激活虚拟环境

Windows（CMD）

.venv\Scripts\activate.bat

Windows（PowerShell）

.venv\Scripts\Activate.ps1

macOS/Linux（bash/zsh）

source .venv/bin/activate

验证激活

激活后终端提示符前会出现 (.venv) 标识，执行以下命令确认环境：

which python  # 输出 .venv/bin/python（macOS/Linux）
where python  # 输出 .venv\Scripts\python.exe（Windows）

3. 退出虚拟环境

deactivate

4. 删除虚拟环境

无需 uv 命令，直接删除环境文件夹即可：

# macOS/Linux
rm -rf .venv

# Windows
rmdir /s /q .venv

三、uv 依赖管理（核心功能）

1. 安装依赖

基础安装（类似 pip install）

# 安装单个包
uv pip install requests

# 安装指定版本包
uv pip install requests==2.31.0

# 安装多个包
uv pip install requests pandas numpy

# 从 requirements.txt 安装
uv pip install -r requirements.txt

# 安装开发依赖（pyproject.toml 中 [dev-dependencies] 部分）
uv pip install -e .[dev]

安装并写入依赖文件

# 安装包并写入 pyproject.toml（推荐，标准化管理）
uv add requests  # 等价于 pip install + 写入 pyproject.toml

# 安装开发依赖并写入
uv add --dev pytest

2. 查看已安装依赖

# 查看所有已安装包（简洁版）
uv pip list

# 查看详细依赖树
uv pip show requests  # 查看单个包的详情（版本、依赖、路径等）
uv pip freeze  # 输出 requirements.txt 格式的依赖列表

3. 更新依赖

# 更新单个包
uv pip install --upgrade requests

# 更新所有包
uv pip install --upgrade all

# 更新 pyproject.toml 中的依赖到最新兼容版本
uv update

4. 卸载依赖

# 卸载单个包
uv pip uninstall requests

# 卸载多个包
uv pip uninstall pandas numpy

# 从 pyproject.toml 中移除依赖
uv remove requests

5. 依赖导出

# 导出当前环境依赖到 requirements.txt
uv pip freeze > requirements.txt

# 导出 pyproject.toml 中的依赖到 requirements.txt
uv export > requirements.txt

# 仅导出生产依赖（排除开发依赖）
uv export --without-dev > requirements.txt

四、uv 高级用法

1. 使用 uv run 直接运行命令（无需激活环境）

无需手动激活虚拟环境，直接通过 uv 调用环境内的命令：

# 运行 Python 脚本（使用 .venv 中的 Python）
uv run python main.py

# 运行第三方工具（如 pytest，无需激活环境）
uv run pytest tests/

2. 配置 uv 镜像源（加速国内下载）

临时使用（单次命令）

uv pip install requests --index-url https://pypi.tuna.tsinghua.edu.cn/simple/

永久配置（全局生效）

# 设置清华镜像源
uv config set install.index-url https://pypi.tuna.tsinghua.edu.cn/simple/

# 查看当前配置
uv config show

3. 基于 pyproject.toml 初始化项目

# 初始化标准 Python 项目（生成 pyproject.toml）
uv init my-project

# 进入项目目录
cd my-project

# 安装项目依赖（根据 pyproject.toml）
uv install

五、常见错误及处理方法

错误1：uv venv --python 3.11 报错：Failed to find Python 3.11

错误原因：本地未安装对应 Python 版本，且 uv 自动下载失败（网络/权限问题）。
处理方法：

1. 手动安装对应版本 Python，或换用本地已有的版本：

   uv venv --python $(which python3.10)  # 使用本地 3.10 版本
   

2. 检查网络，确保能访问 uv 的 Python 下载源，或配置代理：

   export http_proxy=http://your-proxy:port
   export https_proxy=http://your-proxy:port
   

错误2：uv pip install 报错：Permission denied

错误原因：无权限写入系统目录（未使用虚拟环境，或虚拟环境路径权限不足）。
处理方法：

1. 确保先创建并激活虚拟环境，再安装依赖；
2. 若虚拟环境路径权限不足，重新创建环境到有权限的目录：

   uv venv ~/my-venv  # 放在用户目录下
   

错误3：uv run python main.py 报错：ModuleNotFoundError: No module named ‘requests’

错误原因：依赖未安装到 uv 对应的虚拟环境中。
处理方法：

1. 确认依赖已安装：uv pip list | grep requests；
2. 若未安装，执行 uv pip install requests 后再运行；
3. 确认使用 uv run 调用的是虚拟环境内的 Python：uv run which python。

错误4：Windows 执行 uv 命令报错：无法将“uv”识别为内部或外部命令

错误原因：uv 安装路径未加入系统环境变量。
处理方法：

1. 找到 uv 的安装路径（通常在 %USERPROFILE%\.cargo\bin）；
2. 将该路径添加到系统环境变量 PATH；
3. 重启终端后重新执行 uv --version 验证。

错误5：uv add requests 报错：pyproject.toml not found

错误原因：当前目录未初始化 pyproject.toml，无法写入依赖。
处理方法：

1. 先初始化项目：uv init .（当前目录生成 pyproject.toml）；
2. 再执行 uv add requests。

六、补充说明

1. uv 与传统工具对比：
   • 速度：uv 解析依赖速度是 pip 的 10-100 倍，适合大型项目；
   • 兼容性：完全兼容 pip/requirements.txt/pyproject.toml，可无缝替换；
   • 优势：内置虚拟环境管理，无需额外安装 venv/poetry。
2. 常用快捷命令：
   • uv venv：快速创建 .venv 虚拟环境；
   • uv run：免激活运行环境内命令；
   • uv add：安装并写入 pyproject.toml；
   • uv export：导出依赖到 requirements.txt。
3. 注意事项：
   • 避免在系统 Python 环境中直接使用 uv 安装依赖，始终创建虚拟环境；
   • 国内用户建议配置镜像源，提升下载速度；
   • pyproject.toml 是现代 Python 项目的标准配置文件，优先使用 uv add 而非 pip install 管理依赖。