《uv 终极教程：安装、镜像配置与 pip 无缝迁移》

一、uv 安装步骤（三大主流系统）

以下是 uv 的安装步骤和它与 pip 的常用命令对比，方便你快速上手并迁移使用。

推荐方式（官方一键脚本，最快最稳）

1. macOS/Linux

• 打开终端，执行：curl -LsSf https://astral.sh/uv/install.sh | sh。
• 部分 Linux 可能需要加 sudo 以获取权限：curl -LsSf https://astral.sh/uv/install.sh | sudo sh。

1. Windows

• 打开 PowerShell（管理员模式可选），执行：irm https://astral.sh/uv/install.ps1 | iex。
• 若用 CMD，执行：powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"。

1. 验证安装

• 安装后重启终端，执行 uv --version，显示版本号即成功（如 uv 0.1.32）。

备选安装方式

方式	命令	适用场景
pip 安装	pip install uv	快速测试，不推荐用于生产（非最新版，启动稍慢）
pipx 安装	pipx install uv	隔离工具依赖，避免污染全局环境
Homebrew（macOS）	brew install uv	习惯用 Homebrew 管理软件的用户
Cargo（Rust 开发者）	cargo install uv	已安装 Rust 环境，需自定义编译

uv 与 pip 常用命令对比表

功能	pip 命令	uv 兼容命令	uv 原生命令（更推荐）	备注
安装包	pip install 包名	uv pip install 包名	uv add 包名	uv 原生会写入 pyproject.toml 并锁定依赖
从文件安装	pip install -r requirements.txt	uv pip install -r requirements.txt	uv add -r requirements.txt	兼容 pip 的 requirements.txt 格式
卸载包	pip uninstall 包名	uv pip uninstall 包名	uv remove 包名	原生命令会清理无用的间接依赖
列出已安装包	pip list	uv pip list	-	输出格式略有差异
导出依赖清单	pip freeze > requirements.txt	uv pip freeze > requirements.txt	uv export -o requirements.txt	uv 导出更精准，支持锁定依赖版本
创建虚拟环境	python -m venv 环境名	-	uv venv	uv 创建速度更快，自动管理路径
激活虚拟环境	source 环境名/bin/activate（Linux/macOS） 环境名\Scripts\activate（Windows）	-	source .venv/bin/activate（Linux/macOS） .venv\Scripts\activate（Windows）	uv 创建的环境默认在 .venv 目录下
运行脚本	python 脚本名.py	-	uv run 脚本名.py	自动使用项目虚拟环境的 Python
初始化项目	-	-	uv init 项目名	生成 pyproject.toml 等项目文件
安装 Python 版本	-	-	uv python install 3.11	无需额外工具，直接管理 Python 版本

---

关键使用建议

1. 兼容优先 ：若你是从 pip 迁移，可先用 uv pip install 等兼容命令，无缝过渡。
2. 新项目推荐 ：直接用 uv 原生命令（如 uv init、uv add），体验更快的依赖管理和环境创建。
3. 虚拟环境：uv 创建的虚拟环境默认在项目根目录的 .venv 下，无需手动指定路径，更符合现代项目规范。

二、从 pip 迁移到 uv 的 5 步实战清单

这份清单覆盖虚拟环境迁移、依赖锁定、命令替换、问题排查，确保无缝切换，适配新旧项目。

前提

已按照之前的步骤安装好 uv，执行 uv --version 验证安装成功。

第 1 步：导出 pip 旧项目的依赖清单

目的：把 pip 管理的项目依赖导出为 requirements.txt，供 uv 识别。

1. 激活原 pip 虚拟环境
   • Linux/macOS：source venv/bin/activate
   • Windows：venv\Scripts\activate
2. 导出依赖

pip freeze > requirements.txt

3. 退出原环境：deactivate

第 2 步：用 uv 创建新虚拟环境（替代 venv）

uv 创建虚拟环境更快，默认路径为项目根目录的 .venv，更规范。

1. 进入项目根目录
2. 创建 uv 虚拟环境

uv venv

3. 激活 uv 虚拟环境
   • Linux/macOS：source .venv/bin/activate
   • Windows：.venv\Scripts\activate
     激活后终端会显示 (.venv) 前缀。

第 3 步：迁移依赖并锁定版本（核心步骤）

uv 支持两种迁移方式，推荐用原生锁定方式，依赖更稳定。

迁移方式	命令	适用场景
兼容 pip 方式	uv pip install -r requirements.txt	快速迁移，完全兼容旧依赖
uv 原生方式	uv add -r requirements.txt	新项目推荐，自动写入 pyproject.toml 并生成锁定文件 uv.lock

关键优势：uv.lock 是比 requirements.txt 更精准的锁定文件，能固定所有间接依赖的版本，避免"在我电脑能跑"的问题。

第 4 步：替换日常 pip 命令（无缝过渡）

把项目中常用的 pip 命令换成 uv 命令，按下表对应替换即可：

日常操作	原 pip 命令	uv 替代命令	备注
安装单个包	pip install requests	uv add requests	自动更新 pyproject.toml 和 uv.lock
卸载包	pip uninstall requests	uv remove requests	自动清理无用的间接依赖
升级包	pip install --upgrade requests	uv add requests@latest	指定最新版本
查看已装包	pip list	uv list	输出更简洁，按字母排序
导出依赖清单	pip freeze > req.txt	uv export -o req.txt	可导出兼容 pip 的 requirements.txt
运行 Python 脚本	python main.py	uv run main.py	自动使用当前虚拟环境的 Python

第 5 步：常见问题排查（避坑指南）

问题现象	可能原因	解决方法
执行 uv 命令提示"找不到"	安装后未重启终端，环境变量未生效	重启终端，或手动将 uv 路径加入环境变量
安装包时报"网络错误"	uv 默认从 PyPI 下载，网络不稳定	配置国内镜像源： uv config set registry.index-url https://pypi.tuna.tsinghua.edu.cn/simple
部分旧包安装失败	uv 对极老旧包的兼容性待完善	切换回兼容模式安装：uv pip install 旧包名
虚拟环境激活失败（Windows）	系统执行策略限制	以管理员身份打开 PowerShell，执行： Set-ExecutionPolicy RemoteSigned，然后选"Y"

---

三、uv 原生命令的适用场景（推荐用的情况）

当你的项目是现代 Python 项目 （用 pyproject.toml 管理依赖，而非仅 requirements.txt），优先用 uv 原生命令，核心场景包括：

1. 新建/管理项目依赖（核心场景）

# 1. 初始化项目（生成 pyproject.toml）
uv init my_project
cd my_project

# 2. 添加依赖（自动写入 pyproject.toml，替代 pip install）
uv add numpy requests  # 推荐！比 pip install 快数倍

# 3. 移除依赖（自动从 pyproject.toml 删除）
uv remove requests

# 4. 同步依赖（根据 pyproject.toml 安装/更新，替代 pip install -r requirements.txt）
uv sync

# 5. 生成锁文件（锁定依赖版本，确保环境一致）
uv lock

• 优势：自动维护 pyproject.toml（项目依赖清单）和 uv.lock（版本锁文件），团队协作时只需共享这两个文件，uv sync 即可一键还原环境，比 requirements.txt 更规范。

2. 管理 Python 版本/虚拟环境

# 创建虚拟环境（替代 venv 模块）
uv venv

# 管理 Python 版本（安装指定版本的 Python）
uv python install 3.12
uv python use 3.12  # 切换当前项目使用的 Python 版本

3. 运行/构建项目

# 运行 Python 脚本（自动使用虚拟环境）
uv run main.py

# 构建 Python 包（生成 wheel/源码包，替代 setuptools）
uv build

---

四、uv 工具的全局镜像源

通过环境变量配置（全局生效，推荐）

这是最直接且全局生效的方式，适配所有版本的 uv，步骤和之前一致，这里再明确一遍（Windows 系统）：

1.按下 Win + R，输入 sysdm.cpl 回车，打开「系统属性」；

2. 切换到「高级」选项卡 → 点击「环境变量」；

3. 在「用户变量」区域点击「新建」：

变量名：UV_INDEX_URL

变量值：https://pypi.tuna.tsinghua.edu.cn/simple

4. 点击「确定」保存所有设置，关闭所有命令行窗口后重新打开；

5. 验证：执行 uv pip install numpy（用 uv 的 pip 兼容接口安装包），会自动从清华源下载，无需额外参数。

5 个常用 Python 镜像源（均支持 pip/uv）

镜像源名称	镜像源地址	特点
清华大学镜像源	https://pypi.tuna.tsinghua.edu.cn/simple	国内最常用、速度快、更新及时
阿里云镜像源	https://mirrors.aliyun.com/pypi/simple/	阿里云服务器，稳定性高，适合阿里云服务器环境
腾讯云镜像源	https://mirrors.cloud.tencent.com/pypi/simple/	腾讯云节点，南方地区访问速度优
中科大镜像源	https://pypi.mirrors.ustc.edu.cn/simple/	学术机构维护，更新快，无商业限制
豆瓣镜像源	https://pypi.douban.com/simple/	老牌镜像源，配置简单，适合测试/轻量使用

关键验证步骤

配置完成后，新建一个文件，并创建虚拟环境，激活后

uv 默认要求在虚拟环境中安装包

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

uv venv

2. 激活虚拟环境（Windows cmd 命令）

.venv\Scripts\activate

3. 激活后，再安装 numpy（此时会自动使用你配置的清华源）

# 安装一个测试包，观察下载地址是否为清华源
uv pip install numpy -v

在输出日志中会看到类似Downloading from https://pypi.tuna.tsinghua.edu.cn/...的信息，说明镜像源已生效。

你现在看到的这些日志是 uv pip install numpy -v 的详细执行过程，核心意思是：uv 已经成功识别你配置的清华镜像源，在虚拟环境中完成了 numpy 的版本筛选、下载和安装，整个过程完全符合预期，没有报错。下面是逐段拆解这些日志的关键信息，让你清楚每一步在做什么。

日志核心信息拆解

1. 环境准备阶段（前几行）

DEBUG Found `cpython-3.13.11-windows-x86_64-none` at `...\.venv\Scripts\python.exe` (active virtual environment)
DEBUG Using Python 3.13.11 environment at: .venv

• 含义：uv 检测到你已经激活了虚拟环境（.venv），并确认使用该环境下的 Python 3.13.11（避免污染系统 Python）；
• 这是你之前执行 uv venv + 激活环境的结果，符合 uv 的最佳实践。

2. 依赖检查阶段

DEBUG At least one requirement is not satisfied: numpy
DEBUG Adding direct dependency: numpy*

• 含义：uv 检查到当前虚拟环境中没有安装 numpy，需要新增这个依赖包。

3. 镜像源生效关键证据（重点）

DEBUG No cache entry for: https://pypi.tuna.tsinghua.edu.cn/simple/numpy/
DEBUG Sending fresh GET request for: https://pypi.tuna.tsinghua.edu.cn/simple/numpy/
...
DEBUG No cache entry for: https://pypi.tuna.tsinghua.edu.cn/packages/.../numpy-2.4.1-cp313-cp313-win_amd64.whl
DEBUG Sending fresh GET request for: https://pypi.tuna.tsinghua.edu.cn/packages/.../numpy-2.4.1-cp313-cp313-win_amd64.whl

• 核心含义：uv 正在从你配置的清华大学镜像源（而非官方 pypi.org）请求 numpy 包 ，这证明你之前设置的 UV_INDEX_URL 环境变量已经生效！
• 这是最关键的验证点，说明镜像源配置成功。

4. 版本筛选阶段（大量 WARN 行）

WARN Skipping file for numpy: numpy-1.0.1.dev3460.win32-py2.4.exe
WARN Skipping file for numpy: numpy-1.3.0.win32-py2.5.exe
...（一堆类似 WARN 行）

• 含义：uv 会遍历镜像源里所有 numpy 版本，但会跳过和你当前环境不兼容的版本（比如适配 Python 2.4/2.5/3.1 等旧版本的安装包，而你用的是 Python 3.13）；
• 这些 WARN 不是报错，只是正常的版本筛选，无需担心。

5. 版本选择与下载阶段

DEBUG Selecting: numpy==2.4.1 [compatible] (numpy-2.4.1-cp313-cp313-win_amd64.whl)
Downloading numpy (11.7MiB)
 Downloaded numpy

• 含义：uv 最终选中了和你 Python 3.13 兼容的 numpy 2.4.1 版本（64位 Windows 适配包），并从清华源下载完成（11.7MB）。

6. 安装完成阶段

Prepared 1 package in 2.35s
Installed 1 package in 460ms

• 含义：numpy 包的准备（解压、校验）耗时 2.35 秒，实际安装到虚拟环境仅用了 460 毫秒，整个过程成功完成。

关键结论

这些日志没有任何错误，反而证明了两件你最关心的事：

1. 虚拟环境配置成功 ：uv 正确识别并使用了 .venv 虚拟环境，没有污染系统 Python；
2. 清华镜像源配置生效 ：所有下载请求都指向 https://pypi.tuna.tsinghua.edu.cn，而非官方源，下载速度会比直接连国外源快很多。

总结

1. 这些日志是 uv 安装 numpy 的详细过程，核心是从清华镜像源下载并安装了兼容的 numpy 版本；
2. 日志中的 WARN 是正常的版本筛选，不是报错；
3. 关键验证点：日志中出现清华源地址 → 镜像源配置成功；最终显示 Installed 1 package → numpy 安装成功。

你现在可以在虚拟环境中执行 python -c "import numpy; print(numpy.__version__)"，会输出 2.4.1，进一步确认 numpy 已成功安装。