Windows安装uv应优先运行官方PowerShell脚本powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"，自动配置路径；安装后必须新开终端验证uv --version，并立即配置国内镜像源（如清华或阿里云），否则uv python install将因网络问题卡死。
Windows上装uv，别用pip install uv，直接跑官方PowerShell脚本最稳；装完必须配国内镜像，否则首次uv python install大概率卡死在下载Python二进制阶段。
PowerShell安装脚本执行要点
官方脚本是唯一推荐方式，它会自动把uv.exe放进$HOME\.local\bin并修改$PATH。手动用pip install uv看似简单，但会导致后续uv python install失败——因为pip装的是Python包，而uv核心功能（如下载管理Python版本）依赖原生二进制行为。
执行前确认PowerShell策略允许远程脚本：
- 以普通用户身份打开PowerShell（无需管理员）
- 运行：
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" - 若提示“无法加载文件”，说明策略未绕过，必须加
-ExecutionPolicy ByPass参数 - 安装完成后新开一个PowerShell窗口再验证，旧窗口
$PATH未刷新
验证命令：uv --version。如果报“不是内部或外部命令”，说明$PATH没生效，检查是否漏了新开终端，或手动把$HOME\.local\bin加进系统环境变量。
立即学习“Python免费学习笔记（深入）”；
必须配置国内镜像源的三个层级
uv不读pip.conf或pip install -i参数，所有镜像都得单独设。不配的话，uv python install 3.12会连Python官方CDN都打不开，卡在Downloading python-3.12.4-embed-amd64.zip不动。
推荐按优先级顺序配置：
-
全局配置（首选）：创建文件
%USERPROFILE%\.config\uv\config.toml，写入：[registries.pypi] index = "https://mirrors.aliyun.com/pypi/simple/"
-
环境变量兜底：在系统属性→环境变量里新增
UV_INDEX_URL，值为https://mirrors.aliyun.com/pypi/simple/（重启终端生效） -
项目级覆盖（可选）：在项目
pyproject.toml里加[tool.uv] index-url = "https://pypi.tuna.tsinghua.edu.cn/simple/"
注意：三个地方同时存在时，项目级 > 环境变量 > 全局配置。调试时可用uv python list --all看是否能快速列出Python版本列表来验证镜像是否起效。
首次使用必做的三件事
装完不等于能用。Windows用户最容易卡在这几步：
-
先下载一个Python版本：
uv python install 3.12（别跳过！uv venv默认用系统Python，但Windows系统Python常缺dev headers，导致后续uv add编译C扩展失败） -
绑定项目Python版本：
uv python pin 3.12（生成.python-version，让uv venv和uv sync自动对齐） -
初始化项目再建环境：进项目目录后，先
uv init生成pyproject.toml，再uv venv——直接uv venv空目录会建环境但没锁文件，uv sync会报错找不到uv.lock
常见错误：error: failed to parse pyproject.toml，基本是因为当前目录没pyproject.toml却执行了uv sync；error: failed to find a Python interpreter，说明uv python install没成功或uv python pin没运行。
PyCharm识别uv虚拟环境的关键路径
PyCharm不能自动发现uv创建的.venv，必须手动指定解释器路径：
- Windows下真实路径是：
.venv\Scripts\python.exe（不是.venv\Scripts\activate.ps1） - 如果点选后提示“setuptools not found”，立刻执行：
uv add setuptools==79.0.1（高版本如80+会导致PyCharm解析失败） - PyCharm里改完解释器后，务必点“Reload project”按钮，否则依赖树不更新
- 不要在PyCharm终端里用
.venv\Scripts\Activate.ps1激活——uv设计就是免激活，直接uv run script.py即可
最易忽略的一点：uv venv生成的.venv目录默认权限是只读，PyCharm首次加载时可能因写入.idea失败而静默报错，遇到项目结构异常，先右键.venv→属性→取消“只读”勾选。
