python-uv-windows环境安装方案

Windows 基于 uv 的 Python 环境安装方案

范围：Windows 10/11 + PowerShell 环境，Python 3.10 ~ 3.13。

目标：替代 miniforge3 / Anaconda，建立统一、轻量、可锁定的 Python 工程环境。

---

一、决策结论

维度	uv（采用）	miniforge3 / conda	裸 Python + pip
安装体积	~30 MB（单一可执行）	~500 MB+	~100 MB（解释器）
依赖解析速度	秒级（Rust 内核）	慢（10s ~ 数分钟）	中等
依赖锁定	uv.lock（精确到 hash）	conda-lock	无（requirements.txt 弱）
Python 版本管理	自动下载任意版本	受限于 conda 内置	手动装多版本
与 pip 生态兼容	100%（PEP 621）	不兼容（混合求解器）	100%
学习曲线	中（少量新命令）	高（环境语法特殊）	低
跨平台一致性	高（Win/Linux/macOS 同命令）	中	低

采用 uv：体积最小、速度最快、依赖锁定最强、跨平台一致。

---

二、安装

2.1 前置条件

项	要求
系统	Windows 10 1909+ / Windows 11
Shell	PowerShell 5.1+（系统自带）
磁盘	~150 MB（uv + 默认缓存）
网络	需访问astral.sh 或国内镜像站

2.2 一键安装（官方脚本）

PowerShell 执行：

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

安装位置：C:\Users\<用户>\.local\bin\uv.exe，自动写入 User PATH。

2.3 镜像加速（国内必加）

清华源（推荐）：

[Environment]::SetEnvironmentVariable("UV_DEFAULT_INDEX", "https://pypi.tuna.tsinghua.edu.cn/simple", "User")
[Environment]::SetEnvironmentVariable("UV_INDEX_URL", "https://pypi.tuna.tsinghua.edu.cn/simple", "User")

阿里源（备选）：

[Environment]::SetEnvironmentVariable("UV_DEFAULT_INDEX", "https://mirrors.aliyun.com/pypi/simple/", "User")
[Environment]::SetEnvironmentVariable("UV_INDEX_URL", "https://mirrors.aliyun.com/pypi/simple/", "User")

2.4 验证安装

uv --version              # 期望: uv 0.4.x 或更高
where uv                  # 期望: C:\Users\<用户>\.local\bin\uv.exe
uv python list            # 列出 uv 可下载的所有 Python 版本
uv python install 3.12    # 预下载 Python 3.12（可选，uv venv 时自动下载）

---

三、基础命令速查

3.1 虚拟环境

# ✅ 推荐：项目根目录下创建 .venv（VSCode / Ruff 自动识别）
cd D:\myproject
uv venv                       # 默认 .venv，使用 .python-version 锁定的版本

# ✅ 指定 Python 版本（首次创建）
uv venv --python 3.11
uv venv --python 3.13

# ✅ 已存在 .venv 时重建（强制覆盖）
uv venv --python 3.11 --clear
# 或：$env:UV_VENV_CLEAR=1; uv venv --python 3.11

⚠️ .venv 已存在冲突 ：uv venv 不会覆盖现有目录，必须加 --clear 或先 Remove-Item -Recurse .venv。详见 §7.7。

⚠️ 反例（不要模仿） ：跨项目散落创建 D:\venvs\myproject 之类的"集中环境池"------VSCode 无法自动发现、删除无 conda env remove 那种单一命令、迁移时容易遗漏。每个项目自带 .venv 是 PEP 惯例。

3.1.1 命令名不可简写（PowerShell 陷阱）

uv 的子命令必须打完整名 ，不存在 uv v 简写。

# ✅ 正确
uv venv --python 3.13

# ❌ 错误：PowerShell 把 "uv v" 解析成 [uv, v]，"v" 找不到 → 报 CommandNotFoundException
uv v --python 3.13

详见 §7.8。

3.2 激活虚拟环境

.venv\Scripts\Activate.ps1

退出：deactivate。

3.3 包管理

# 安装包（无需先激活环境，uv 自动识别当前目录的 .venv）
uv pip install requests
uv pip install requests==2.31.0
uv pip install -r requirements.txt

# 依赖锁定（推荐：生成 uv.lock，精确到 hash，提交 git）
uv lock

# 依赖收敛（pyproject.toml / requirements.in → requirements.txt）
uv pip compile requirements.in -o requirements.txt

# 同步环境（按 requirements.txt 精确安装）
uv pip sync requirements.txt

# 升级 / 卸载 / 查询
uv pip install --upgrade requests
uv pip uninstall requests
uv pip list
uv pip freeze

3.4 免激活运行

uv run python main.py
uv run pytest
uv run jupyter lab
uv run --with requests python -c "import requests; print(requests.__version__)"

uv run 自动使用项目 .venv，没有则临时创建（--with 可注入临时依赖）。

3.5 最小 demo（hello-uv）

完整跑通 5 步，验证 uv 工具链可用：

mkdir D:\hello-uv; cd D:\hello-uv                                # 1. 建项目目录
uv init                                                           # 2. 初始化（生成 pyproject.toml / .python-version / main.py）
uv venv --python 3.12                                             # 3. 建虚拟环境
uv add rich                                                       # 4. 加运行时依赖
uv run python -c "from rich import print; print('[green]Hello from uv![/green]')"   # 5. 运行

预期输出：

Hello from uv!

---

四、项目初始化模板

4.1 通用 Python 项目

mkdir myproject
cd myproject
uv init                                  # 生成 pyproject.toml + .python-version + main.py + README.md
uv add requests                          # 添加运行时依赖
uv add --dev pytest ruff                 # 添加开发态依赖
uv run python main.py                    # 立即运行

产出结构：

文件	作用
pyproject.toml	项目元数据 + 依赖声明（PEP 621）
uv.lock	锁定依赖（精确到 hash，提交 git）
.python-version	锁定 Python 版本（如3.12）
.venv/	虚拟环境目录（加入.gitignore）

4.2 可发布包项目

uv init --package                        # 生成 src/ 包结构
uv build                                 # 构建 sdist + wheel
uv publish                               # 发布到 PyPI（需配置 token）

4.3 Git 提交建议

.gitignore 必加：

.venv/
__pycache__/
*.pyc
dist/
build/
*.egg-info/

提交：

git add pyproject.toml uv.lock .python-version .gitignore
git commit -m "chore: bootstrap project with uv"

---

五、VSCode 集成

5.1 推荐扩展

扩展 ID	作用
ms-python.python	Python 基础语言服务
ms-python.vscode-pylance	类型检查、智能提示
charliermarsh.ruff	Linter + Formatter（替代 flake8 + black，10x 速度）

5.2 工作区配置（.vscode/settings.json）

{
    "python.defaultInterpreterPath": "${workspaceFolder}/.venv/Scripts/python.exe",
    "[python]": {
        "editor.formatOnSave": true,
        "editor.defaultFormatter": "charliermarsh.ruff"
    },
    "python.testing.pytestEnabled": true,
    "python.analysis.autoImportCompletions": true
}

5.3 手动选择解释器

Ctrl+Shift+P → Python: Select Interpreter → 选择 .venv\Scripts\python.exe。

---

六、从 conda / miniforge 迁移

6.1 命令对照表

conda / miniforge	uv 等价命令
conda create -n myenv python=3.12	uv venv myenv --python 3.12
conda activate myenv	.venv\Scripts\Activate.ps1
conda install requests	uv pip install requests
conda list	uv pip list
conda env export > env.yml	uv pip freeze > requirements.txt
conda env create -f env.yml	uv pip sync requirements.txt
conda env remove -n myenv	Remove-Item -Recurse .venv
conda search requests	uv pip index versions requests（或查 PyPI 官网）

6.2 迁移步骤（标准化流程）

1. 导出依赖：conda env export --no-builds > env.yml 或 pip freeze > requirements.txt
2. 删除 conda 环境：conda deactivate && conda env remove -n myenv
3. 卸载 miniforge3：控制面板 → 程序与功能 → 卸载（仅当确认所有项目都已迁移）
4. 清理 PATH 残留：删除用户/系统 PATH 中的 miniforge3、conda、Anaconda 条目（重启生效）
5. 安装 uv：见 §2.2
6. 配置镜像：见 §2.3
7. 创建环境：uv venv
8. 安装依赖：uv pip install -r requirements.txt
9. 验证：uv run python -c "import <关键包>; print(<关键包>.__version__)"

---

七、常见踩坑

7.1 PowerShell 禁止运行脚本

错误：xxx.ps1 无法加载，因为在此系统上禁止运行脚本
解决：Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

7.2 SSL 证书错误（公司内网/代理）

[Environment]::SetEnvironmentVariable("UV_INSECURE_HOST", "pypi.tuna.tsinghua.edu.cn", "User")

或临时跳过：

$env:UV_INSECURE_HOST="pypi.tuna.tsinghua.edu.cn"; uv pip install requests

7.3 路径含中文/空格

uv 完全支持。避免使用 # % & 等 shell 特殊字符。

7.4 删除虚拟环境

uv 不提供 uv venv remove，直接删目录：

Remove-Item -Recurse -Force .venv

7.5 VSCode 找不到解释器

确认 .venv 已存在且 python.defaultInterpreterPath 路径正确；按 Ctrl+Shift+P → Python: Select Interpreter 手动重选。

7.6 清华镜像同步延迟

极少数新发布包可能延迟 10 ~ 30 分钟；紧急时临时切回官方源：

Remove-Item Env:UV_DEFAULT_INDEX -ErrorAction SilentlyContinue
uv pip install <包名>

7.7 .venv 已存在 → uv venv 失败

错误：A virtual environment already exists at: .venv
      error: Failed to create virtual environment
hint: Use the `--clear` flag or set `UV_VENV_CLEAR=1` to replace the existing venv

根因：uv 默认拒绝覆盖已有虚拟环境（保护已装的依赖不被误删）。

修复三选一：

# 方案 1：重建（推荐，仅在 .venv 没装东西或已不再需要时）
uv venv --python 3.11 --clear

# 方案 2：单次环境变量（不想养成全局习惯时）
$env:UV_VENV_CLEAR=1
uv venv --python 3.11
Remove-Item Env:UV_VENV_CLEAR    # 用完即清

# 方案 3：手动删目录再重建（彻底干净）
Remove-Item -Recurse -Force .venv
uv venv --python 3.11

7.8 uv v --python 3.13 → CommandNotFoundException

错误：v : 无法将"v"项识别为 cmdlet、函数、脚本文件或可运行程序的名称

根因 ：uv 没有 v 子命令（不像 git 可以简写为 git c），PowerShell 把第二个 token v 当成独立命令名查找，自然找不到。

修复 ：打完整子命令名：

# ✅ 正确
uv venv --python 3.13
uv venv --python 3.13 --clear

# ❌ 错（手快简写）
uv v --python 3.13

经验 ：uv 的子命令都很短（venv/add/run/lock/sync/tree），没必要简写。简写带来的歧义大于节省的击键数。