用 uv 管理 Python：一键建虚拟环境、秒装依赖、常见报错排查

你将得到什么

uv 是一个速度很快的 Python 工具（可用于安装包、创建虚拟环境、生成/同步依赖锁定文件等）。跟着本文做一遍，你可以把“装 Python 依赖这件事”变成可复制、可回滚、跨机器一致的流程。

• 快速安装 uv（Windows/macOS）
• 创建项目虚拟环境（不污染系统 Python）
• 秒装依赖、生成锁定文件、在新机器复现
• 镜像加速与网络问题排查
• 常见报错定位：Python 版本不匹配、权限、编译依赖等

准备工作：确认你要用的 Python 版本

建议：先决定项目的目标 Python 版本（例如 3.11 或 3.12），并在团队内统一。后续依赖锁定、CI 运行都会更稳定。

1. 在终端执行 python --version 或 py -V（Windows）查看当前版本。
2. 如果你的电脑装了多个 Python，先记下你希望项目使用的那个版本号。

第1步：安装 uv（Windows / macOS）

uv 官方提供了多种安装方式，下面给出两种“最常用”的做法，按你的环境选其一：

方式A：使用官方安装脚本（推荐）

• macOS / Linux：curl -LsSf https://astral.sh/uv/install.sh | sh
• Windows（PowerShell）：powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

安装完成后执行 uv --version，能输出版本号即成功。

方式B：通过包管理器安装（可选）

• macOS（Homebrew）：brew install uv
• Windows（Scoop/winget）：视你的环境而定（如已使用这些工具再选）

第2步：在项目目录创建虚拟环境

进入你的项目目录（没有就新建一个文件夹），然后执行：

uv venv

它会在当前目录创建一个虚拟环境（通常是 .venv）。

激活虚拟环境：

• Windows PowerShell：.venv\ s\Activate.ps1
• macOS / Linux：source .venv/bin/activate

激活后再运行 python -V，确认输出来自虚拟环境。

第3步：安装依赖（更快的 pip 体验）

如果你已有 requirements.txt：

uv pip install -r requirements.txt

如果你要装单个包，例如 requests：

uv pip install requests

小技巧：安装完成后可以导出一份当前环境的冻结依赖，方便复现：

uv pip freeze > requirements.lock.txt

（团队协作时建议明确：谁负责更新锁定文件、如何审核变更。）

第4步：常用镜像加速（网络慢/超时的解决思路）

当你遇到下载慢、超时、连接重置时，优先按下面顺序排查：

1. 确认网络代理/公司网络策略：是否需要代理？是否拦截了 pypi.org？
2. 改用稳定的镜像源：例如设置 PIP 的 index-url（适用于 uv 的 pip 子命令）。

示例（临时指定镜像）：

uv pip install -i https://pypi.tuna.tsinghua.edu.cn/simple somepackage

如果你希望长期生效，可以在 pip 配置里设置 index-url（不同系统路径不同，按你的环境配置）。

第5步：把环境“固定下来”（避免我能跑你不能跑）

最常见的翻车点不是代码，而是环境不一致。建议你至少做到以下两点：

• 把 .venv 加入 .gitignore（不要提交虚拟环境目录）
• 提交明确的依赖声明（如 requirements.txt 或项目使用的依赖文件）

当同事/新机器拉取项目后，只需要：

uv venv uv pip install -r requirements.txt

即可复现。

常见报错与排查（快速对照表）

1）提示 Python 版本不匹配

• 现象：安装包失败，或运行时报错“requires Python >= …”。
• 处理：升级/切换项目目标 Python 版本；或降低依赖版本到兼容范围。

2）Windows 执行脚本被限制（Activate.ps1 运行失败）

• 现象：PowerShell 报 ExecutionPolicy 限制。
• 处理：临时允许当前会话脚本运行，或改用其他终端（按公司安全策略操作）。

3）安装带编译的依赖失败（如 cryptography、l 、opencv 等）

• 现象：出现编译器相关错误、缺少 header、wheel 构建失败。
• 处理：优先选择有预编译 wheel 的版本；或安装系统依赖/编译工具链；在 macOS 注意 Xcode Command Line Tools。

4）SSL/证书相关错误、连接超时

• 现象：CERTIFICATE_VERIFY_FAILED、ReadTimeout、Connection reset。
• 处理：检查系统时间、代理证书、公司中间人代理；必要时切换网络或使用镜像源。

推荐的“最小正确姿势”清单

• 项目根目录固定使用 .venv 虚拟环境
• 依赖文件有明确入口（requirements 或其他依赖描述）
• README 写清楚三条命令：uv venv / uv pip install -r ... / python main.py
• 遇到问题先看报错的第一段（往往就是版本或网络）

结语

把环境管理流程固定下来之后，你会发现“装依赖”不再是玄学。后续如果你希望把依赖锁定、CI、发布打包也串起来，可以在此基础上继续完善。