用 uv 替代 pip：一个 Python 开发者的真实体验（Windows 为主，跨平台兼容）

坦白说，一开始我也是拒绝的。直到我在 Windows 上试了 uv，再也不用面对那堆烦人的路径问题和慢得要死的 pip…

写在前面

我是从什么时候决定彻底抛弃 pip 的？大概是上个月，我在 Windows PowerShell 里等 pip 安装依赖，等了 5 分钟还在 “Collecting packages…”，而且最后还报了个路径太长的错误。那一刻我真的崩溃了。

朋友推荐我试试 uv，我当时还想：“不就是另一个包管理工具吗？Python 在 Windows 上本来就够难用的了，再多个工具有啥用？”

现在？我的所有新项目都用 uv 了，包括 Windows、macOS 和 Linux 上的项目。

🎁 福利：免费 AI Tokens 助你开发

写这篇文章的时候，我正在用智谱 GLM-4.7 模型帮我 review 代码和写文档。说实话，比我之前用的很多模型都聪明，特别是在理解 Python 项目结构和给出具体建议方面。

如果你也想在开发时用 AI 辅助（比如代码 review、写文档、debug），推荐注册智谱大模型平台，现在通过邀请链接注册能拿 2000 万 Tokens：

• 邀请链接：https://www.bigmodel.cn/invite?icode=Ssx3UdmC76nwa7bdO5B1F0jPr3uHog9F4g5tjuOUqno%3D
• 平台：智谱大模型开放平台 BigModel.cn
• 模型：GLM-4.7（推理、代码、智能体能力都很强）

2000 万 Tokens 够用很久了，反正我是先注册了再慢慢研究的。

所以 uv 到底是啥？

简单说，uv 就是 Rust 团队 Astral（也是 Ruff 的作者）搞出来的 Python 包管理器。它想用 Rust 的速度优势，把 pip、poetry、pyenv、pipx 这些工具的活全干了。

在 Windows 上特别有用，因为它解决了几个老大难问题：

• 路径长度限制（Windows 260 字符路径限制）
• 虚拟环境激活（再也不用记 venv\\Scripts\\activate 了）
• Python 版本管理（比 pyenv-win 好用多了）
• 速度（在 Windows 上比 pip 快得更多，因为 pip 在 Windows 上本来就更慢）

为什么我选择了 uv（Windows 用户特别需要看）

速度真的不是一个量级

别信广告，信疗效。这是我在 Windows 11 + SSD 上的测试数据：

场景：安装 Django + DRF + Celery（ warm cache ）
pip (Windows): 2 分钟 15 秒
poetry (Windows): 1 分钟 20 秒
uv (Windows): 2.1 秒

是的，你没看错。Windows 上 uv 的优势更明显。

第一次跑的时候我还以为出 bug 了，怎么这么快就完了？

Windows 上的路径问题终于解决了

用过 Python 的 Windows 用户都知道， dreaded “path too long” 错误。

以前用 pip 安装某些包（比如 tensorflow、pytorch）时，经常遇到：

Could not install packages due to an EnvironmentError: [Errno 2] No such file or directory:
'C:\\\\Users\\\\…\\\\site-packages\\\\some_package\\\\…\\\\very_long_path'

uv 的缓存机制避免了这个问题，因为它使用了更智能的路径管理。

我受够了 Windows 上的工具链碎片化

以前我在 Windows 上的 Python 项目工具链长这样：

• pyenv-win（经常出问题，而且不支持所有 Python 版本）
• poetry（慢，而且有时候 PowerShell 激活虚拟环境有问题）
• pipx（装全局工具）
• 手动管理 venv（python -m venv venv，然后 venv\\Scripts\\activate）
• pip（应急用）

现在？一个 uv 全搞定。而且 再也不用手动激活虚拟环境了！

安装：Windows 最简单

Windows（推荐方式）

方法 1：PowerShell 安装（最方便）

# 在 PowerShell 中运行（可能需要管理员权限）
irm https://astral.sh/uv/install.ps1 | iex

# 验证安装
uv —version
# 输出：uv 0.10.0

安装完成后，重启 PowerShell，然后就可以用了。

方法 2：使用 pip（如果你已经有 Python）

pip install uv

# 或者用户级别安装（不需要管理员权限）
pip install —user uv

方法 3：从 GitHub Releases 下载

去 https://github.com/astral-sh/uv/releases 下载 uv-x86_64-pc-windows-msvc.zip，解压后把 uv.exe 放到一个在你的 PATH 里的文件夹（比如 C:\\tools 或 C:\\Users\\你的用户名\\.local\\bin）。

macOS / Linux

# macOS / Linux 一键安装
curl -LsSf https://astral.sh/uv/install.sh | sh

# 或者使用 pip
pip install uv

实际用法：Windows 用户的福音

场景一：从零开始一个新项目（Windows PowerShell）

以前我在 Windows 上开新项目是这样的：

# 痛苦的旧方式
mkdir my-project
cd my-project
python –m venv venv
# 然后要记得激活！不同的 shell 命令还不一样
.\\venv\\Scripts\\Activate.ps1 # PowerShell
# 或者
venv\\Scripts\\activate.bat # CMD
# 然后才开始安装依赖
pip install ...

常见问题：

• PowerShell 执行策略阻止脚本运行
• 忘记激活虚拟环境，装到了系统 Python
• CMD 和 PowerShell 的激活命令不一样

现在用 uv：

# Windows PowerShell
uv init my-project
cd my-project
# 完事了！真的就这么简单

uv 会自动：

• 创建虚拟环境（在 .venv 目录）
• 生成 pyproject.toml
• 设置好目录结构
• 初始化 git
• 而且你不需要手动激活虚拟环境！

场景二：加依赖（Windows 为主，附带 macOS/Linux）

# Windows PowerShell
# 加生产依赖
uv add requests
uv add "fastapi>=0.100" "pydantic>=2.0"

# 加开发依赖（测试、格式化这些）
uv add —dev pytest black ruff mypy

# 加文档用的依赖（单独分组，干净）
uv add —group docs mkdocs mkdocs-material

macOS/Linux 上命令完全一样：

# macOS / Linux
uv add requests
uv add –dev pytest black ruff mypy

Windows 用户特别注意：

• 不需要激活虚拟环境！
• 不需要担心路径问题！
• PowerShell、CMD、Git Bash 都能用，命令一样！

场景三：运行代码（跨平台通用）

这是我最喜欢的功能，所有平台命令完全一样：

# Windows PowerShell
uv run python main.py

# 运行 pytest（不需要全局安装）
uv run pytest

# 运行特定的包
uv run ruff check .
uv run black .

# macOS / Linux（命令完全一样！）
uv run python main.py
uv run pytest
uv run ruff check .

重点：uv run 会自动：

再也不用手动激活虚拟环境了！这对于 Windows 用户来说是巨大的便利。

场景四：管理 Python 版本（Windows 特别方便）

以前 Windows 上管理 Python 版本很头疼，pyenv-win 经常出问题。现在 uv 让这件事变得简单：

# Windows: 安装 Python 3.12
uv python install 3.12

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

# 给项目固定 Python 版本
uv python pin 3.12
# 这会创建一个 .python-version 文件

# 快速切换版本测试
uv run —python 3.11 python —version
uv run —python 3.12 python —version

macOS/Linux：

# 同样的命令！
uv python install 3.12
uv python pin 3.12

Windows 用户的福音：

• 自动下载并安装 Python，不需要手动去 python.org 下载安装包
• 不需要设置 Windows 的环境变量
• 不同项目可以用不同版本的 Python，不会冲突

场景五：运行一次性脚本（内联依赖）

你有没有这种经历：写了个 Python 脚本处理数据，但需要 pandas，然后就开始纠结 “要不要为这个脚本建个 venv”。

# analyze_data.py
# /// script
# dependencies = ["pandas>=2.0.0", "openpyxl>=3.1.0"]
# ///

import pandas as pd

# 读取 Excel 文件
df = pd.read_excel("data.xlsx")
print(df.describe())

# Windows: 直接运行，自动处理依赖
uv run analyze_data.py
# 自动创建临时环境，装依赖，运行，清理

# macOS / Linux: 命令完全一样
uv run analyze_data.py

特别适合：

• 数据处理脚本
• 自动化任务
• 一次性工具
• 不需要为每个小脚本都创建项目

场景六：安装全局工具（替代 pipx）

以前 Windows 上用 pipx 装 CLI 工具有时候会有问题，现在 uv 完美解决：

# Windows: 临时用一下某个工具
uvx cowsay "Hello from Windows!"

# 永久安装工具
uv tool install ruff
uv tool install black
uv tool install mypy

# 之后直接在命令行使用
ruff check .
black .
mypy src/

# macOS / Linux
uvx cowsay "Hello from macOS!"
uv tool install ruff

Windows 用户注意：

• 安装后可能需要重启 PowerShell 才能找到命令
• 工具会被安装到 uv 的工具目录，并自动添加到 PATH

实战：Windows 上的真实项目

案例 1：搭建 FastAPI 服务（Windows 开发，Linux 部署）

上周我在 Windows 上用 uv 搭了个微服务，然后部署到 Linux 服务器，完整流程：

# ========== Windows 开发环境 ==========

# 1. 初始化项目
uv init user-service
cd user-service

# 2. 加依赖
uv add fastapi uvicorn[standard] sqlalchemy pydantic-settings
uv add —dev pytest pytest-asyncio httpx

# 3. 写代码（main.py 等）

# 4. 开发时运行（Windows 上测试）
uv run uvicorn main:app —reload
# 自动使用虚拟环境，不需要手动激活！

# 5. Windows 上测试
uv run pytest

# 6. 锁定依赖（生成 uv.lock）
uv lock

# 7. 提交代码到 git
# uv.lock 文件一定要提交！
git add .
git commit –m "Initial commit with uv"

# ========== Linux 服务器部署 ==========

# 1. 克隆代码
git clone https://github.com/your-repo/user-service.git
cd user-service

# 2. 安装相同版本的 Python
uv python install 3.12

# 3. 同步依赖（使用 uv.lock 确保版本一致）
uv sync

# 4. 运行
uv run uvicorn main:app –host 0.0.0.0 –port 8000

跨平台一致性：因为 uv.lock 文件的存在，Windows 开发和 Linux 部署的依赖版本完全一致，再也不会出现 “在我机器上能跑” 的问题。

案例 2：数据科学项目（Windows + WSL2）

很多数据科学家在 Windows 上用 WSL2，uv 让环境管理变得简单：

# ========== Windows 上初始化 ==========
uv init ml-project
cd ml-project

# 锁定 Python 3.11（很多 ML 库对 3.12 支持还不完善）
uv python pin 3.11

# 加依赖
uv add numpy scipy scikit-learn
uv add pandas matplotlib seaborn
uv add jupyter ipykernel

# 生成 lock 文件
uv lock

git add .
git commit –m "Setup ML project with uv"

# ========== WSL2 Ubuntu 上运行 ==========
cd /mnt/c/path/to/ml-project

# 同步环境
uv sync

# 注册 Jupyter kernel（Windows 上的 Jupyter 也能识别）
uv run python -m ipykernel install –user –name ml-project

# 启动 Jupyter
uv run jupyter lab

技巧：你可以在 Windows PowerShell 和 WSL2 之间无缝切换，使用同一个项目目录和相同的 uv 命令。

案例 3：写个 CLI 工具并发布到 PyPI

这是我在维护的一个开源 CLI 工具，支持 Windows/macOS/Linux：

# ========== Windows 上开发 ==========
uv init git-commit-helper
cd git-commit-helper

# CLI 必备库
uv add click rich

# 开发工具
uv add —dev pytest pytest-cov

# 编辑 pyproject.toml 添加入口点
notepad pyproject.toml

在 pyproject.toml 最后添加：

[project.scripts]
gch = "git_commit_helper.main:cli"

# 本地安装测试
uv pip install –e .

# 测试 CLI
gch —help
gch "feat: add new feature"

# 构建（生成 wheel 和 sdist）
uv build
# 输出：
# dist/git_commit_helper-0.1.0-py3-none-any.whl
# dist/git_commit_helper-0.1.0.tar.gz

# 发布到 PyPI
uv publish —token $env:PYPI_TOKEN

跨平台构建：uv 构建的 wheel 是跨平台的，Windows 上构建的包可以在 macOS/Linux 上安装。

案例 4：CI/CD GitHub Actions（跨平台测试矩阵）

这是我现在用的 GitHub Actions 配置，测试 Windows、macOS、Linux：

name: Test
on: [push, pull_request]

jobs:
test:
runs-on: ${{ matrix.os }}
strategy:
matrix:
os: [ubuntu–latest, windows–latest, macos–latest]
python: ["3.10", "3.11", "3.12"]

steps:
– uses: actions/checkout@v4

– name: Install uv
uses: astral–sh/setup–uv@v3
with:
version: "0.10.0"

– name: Setup Python
run: uv python install ${{ matrix.python }}

– name: Install deps
run: uv sync ––dev

– name: Run linting
run: |
uv run ruff check .
uv run ruff format –check .

– name: Run tests
run: uv run pytest ––cov

关键点：

• 同样的 workflow 文件，测试所有平台
• uv 在每个平台上都能正常工作
• 测试矩阵快速完成（uv 的快体现在 CI 上更明显）

Windows 上踩过的坑（以及解决方法）

坑 1：PowerShell 执行策略

症状：运行 uv 安装脚本时，PowerShell 报错：

无法加载脚本，因为在此系统上禁止运行脚本

解决：

# 以管理员身份运行 PowerShell，然后执行：
Set-ExecutionPolicy –ExecutionPolicy RemoteSigned –Scope CurrentUser

# 或者只针对当前会话
Set-ExecutionPolicy –ExecutionPolicy Bypass –Scope Process

坑 2：Windows Defender / 杀毒软件拦截

症状：安装后 uv 被 Windows Defender 拦截或删除。

解决：

坑 3：中文路径问题

症状：项目在中文路径下（如 C:\\Users\\用户名\\文档\\项目），某些包安装失败。

解决：

# 方法 1：把项目移到英文路径
# 例如：C:\\projects\\my-project

# 方法 2：设置环境变量（PowerShell）
$env:UV_CACHE_DIR = "C:\\uv-cache"
uv sync

# 或者在系统环境变量中永久设置 UV_CACHE_DIR

坑 4：公司内网的私有 PyPI

症状：公司内网有私有 PyPI，uv 找不到内部包。

解决：编辑 pyproject.toml：

[[tool.uv.index]]
name = "company"
url = "https://pypi.company.com/simple"
priority = "primary"

[[tool.uv.index]]
name = "pypi"
url = "https://pypi.org/simple"

如果内网需要代理：

# PowerShell 中设置代理
$env:HTTP_PROXY = "http://proxy.company.com:8080"
$env:HTTPS_PROXY = "http://proxy.company.com:8080"
uv sync

坑 5：某些包编译失败（如 Pillow、lxml）

症状：安装某些需要编译 C 扩展的包时失败。

解决：

# 方法 1：强制使用预编译的 wheel
uv pip install pillow —only-binary :all:

# 方法 2：安装 Visual Studio Build Tools（如果需要编译）
# 下载地址：https://visualstudio.microsoft.com/visual-cpp-build-tools/

# 方法 3：使用 conda 的预编译包（混合使用）
# 先用 conda 装编译好的包，再用 uv 管理其他依赖

坑 6：VS Code 找不到 Python 解释器

症状：在 VS Code 中，Python 扩展检测不到 uv 创建的虚拟环境。

解决：

# 方法 1：在 VS Code 中手动选择解释器
# Ctrl+Shift+P -> "Python: Select Interpreter" -> 选择 .venv 目录下的 python.exe

# 方法 2：创建 .vscode/settings.json
# 内容：
{
"python.defaultInterpreterPath": "${workspaceFolder}/.venv/Scripts/python.exe"
}

# 方法 3：使用 uv 的 VS Code 扩展（未来可能会有）

你可能想问的

Q: uv 在 Windows 上稳定吗？

A: 我用 3 个月了，包括 Windows 11、Windows Server 2019，都很稳定。Astral 团队对 Windows 支持得很好。

Q: 我要不要把现有的 Windows Python 项目都迁移到 uv？

A:

• 新项目：直接用 uv，别犹豫
• 老项目：如果依赖管理很乱，或者经常遇到路径问题，值得迁移
• 迁移成本：很低，基本就是把 pip install 改成 uv add，requirements.txt 可以用 uv pip compile 迁移

Q: uv 和 conda 怎么选？

A:

• 需要科学计算包（PyTorch、TensorFlow 等）：先用 conda 装这些大包装好的版本，然后用 uv 管理其他纯 Python 依赖
• 纯 Python 项目：直接用 uv
• 我的做法：用 uv 管理所有项目，只有特别难装的科学计算包才用 conda

Q: 缓存文件很大怎么办？

# Windows: 查看缓存大小
(Get-ChildItem –Recurse (uv cache dir) | Measure-Object –Property Length –Sum).Sum / 1GB

# 清理缓存
uv cache clean

# 我通常每个月清理一次，能省几个 G

Q: 在哪里获取帮助？

• GitHub Issues: https://github.com/astral-sh/uv/issues
• Discord: https://discord.gg/astral-sh （响应很快，包括 Windows 相关问题）
• 官方文档: https://docs.astral.sh/uv/

总结：Windows Python 开发者的救星

说实话，作为一个常年在 Windows 上做 Python 开发的人，我受够了：

• pip 慢得像蜗牛
• 路径长度限制报错
• 虚拟环境激活命令记不住（CMD、PowerShell、Git Bash 都不一样！）
• pyenv-win 经常抽风
• “在我机器上能跑” 的跨平台问题

uv 解决了这些问题，而且做得很好：

当然也有要注意的地方：

• 某些老旧包可能需要特殊处理
• 中文路径偶尔会有问题（建议用英文路径）
• 团队成员需要时间适应

但总的来说，uv 是我 2025 年最满意的开发者工具之一。如果你还在 Windows 上用 pip 苦苦挣扎，强烈推荐花半小时体验一下 uv。

参考

• 官方文档：https://docs.astral.sh/uv/
• GitHub：https://github.com/astral-sh/uv
• Windows 安装指南：https://docs.astral.sh/uv/getting-started/installation/

最后更新: 2026-02-05 基于 uv 版本: 0.10.0 作者: 一个被 uv 拯救的 Windows Python 开发者 测试环境: Windows 11, PowerShell 7.4, Python 3.12