【教程】Windows 最全 uv 使用教程（替代pip/venv，解决uv不是内部命令报错）

LIUQIA

【教程】Windows 最全 uv 使用教程（替代pip/venv，解决uv不是内部命令报错）
一、前言
uv 是目前最快的 Python 包管理器 + 虚拟环境工具，速度吊打原生 pip、venv，可完全替代 poetry、pipenv。
很多新手装完 uv 会遇到经典报错：“uv 不是内部或外部命令”，本文给出永久解决方案 + 全套可复制代码流程。
适用系统：Win10 / Win11
适用 Python：3.12 / 3.13 / 3.14
二、安装 uv（两种方法）
方法1：官方一键安装（推荐）
PowerShell 复制执行：
irm https://astral.sh/uv/install.ps1 | iex
✅ 安装完成后 必须关闭所有终端，重新打开 才能生效。
方法2：pip 安装（网络不稳首选）
py -3.14 -m pip install uv
三、解决：'uv' 不是内部或外部命令
原因：uv 安装路径未写入系统 PATH。
临时万能写法（不用改环境变量，100%能用）
所有 uv 命令前面加：py -3.14 -m uv

查看版本

py -3.14 -m uv --version

查看本机所有 Python

py -3.14 -m uv python list
四、完整新项目标准流程（可直接全套复制）

1. 创建项目 + 初始化
   mkdir uv_demo
   cd uv_demo
   py -3.14 -m uv init
2. 锁定 Python 版本为 3.14
   py -3.14 -m uv python pin 3.14
3. 创建虚拟环境 .venv
   py -3.14 -m uv venv --python 3.14
   ⚠️ 更换 Python 版本必须 删除旧虚拟环境重建：
   Remove-Item -Recurse -Force .venv
4. 激活虚拟环境
   .venv\Scripts\Activate.ps1
   激活成功后终端前面出现 (.venv)，此时可以直接简写 uv 命令。
   如果禁止执行脚本，执行一次：
   Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
   五、常用依赖管理代码（激活环境后）
   安装第三方库

   安装最新版

   uv add requests

指定版本安装

uv add flask==3.0.0

开发依赖（仅调试用）

uv add --dev pytest
卸载库
uv remove requests
同步项目所有依赖（克隆别人项目必备）
uv sync
运行代码
python main.py

不激活环境也能运行

uv run python main.py
退出虚拟环境
deactivate
六、旧项目（requirements.txt）迁移 uv
py -3.14 -m uv venv
.venv\Scripts\Activate.ps1
uv pip install -r requirements.txt
七、VSCode 搭配 uv 使用

1. Ctrl+Shift+P
2. 选择 Python: Select Interpreter
3. 选中项目内：.venv/Scripts/python.exe
   即可全程使用 uv 虚拟环境运行、调试。
   八、重点踩坑总结（必看）
4. uv 没有自带 IDLE，IDLE 属于 Python 本体组件。
5. 微软商店版 Python3.14 阉割 tkinter，永远打不开 IDLE，直接用 VSCode。
6. 未激活环境报错，统一用 py -3.14 -m uv xxx 万能写法。
7. 换 Python 版本必须删 .venv，不能原地升级。
8. 安装 uv 后必须重启终端才能识别 PATH。
   九、高频命令速查表
   【未激活环境写法】
   py -3.14 -m uv python list
   py -3.14 -m uv python pin 3.14
   py -3.14 -m uv venv --python 3.14
   py -3.14 -m uv sync
   【激活后简写】
   uv add xxx
   uv remove xxx
   uv sync
   uv run python xxx.py

Blazingsun

学习一下👏

OSmile

不错不错，内容挺全

涛之雨

关于：“换 Python 版本必须删 .venv，不能原地升级。”
以下内容由D老师生成

这个说法不完全准确，且已过时。在当前的 uv 版本中，更换 Python 版本不一定必须手动删除 .venv 目录。

具体情况取决于你更换的是补丁版本还是次要/主要版本：

✅ 补丁版本升级：可以自动完成

如果你的目标是升级到同一 minor 版本的最新补丁（例如从 Python 3.12.4 升级到 3.12.6），uv 可以自动处理。

从 uv 0.10.0 版本开始，Python 补丁版本升级功能已经稳定。当执行 uv python upgrade 命令升级 Python 版本后，由 uv 创建的虚拟环境会自动使用新版本。

注意：如果虚拟环境是使用精确的补丁版本号创建的（例如 uv venv -p 3.10.8），它不会被自动升级。

⚠️ 次要/主要版本更换：通常需要重建

如果你需要更换 Python 的次要版本或主要版本（例如从 Python 3.11 换到 3.12），情况就不同了。uv 本身并没有提供一个直接“原地升级”环境内 Python 大版本的功能。

在这种情况下，常见的做法确实是删除并重建虚拟环境。直接尝试切换可能会导致如下错误：

error: Project virtual environment directory `.venv` cannot be used because it is
not a compatible environment but cannot be recreated because it is not a
virtual environment

这通常是手动修改或非 uv 创建的环境导致的。

💡 推荐做法：使用 --clear 标志

现在，uv 提供了更优雅的方式来处理重建。在 uv 0.10.0 版本后，uv venv 命令要求使用 --clear 标志来明确允许删除已存在的虚拟环境。

因此，更换 Python 版本（尤其是大版本）时，推荐的标准流程是：

1. 修改项目中的 .python-version 文件或 pyproject.toml 中的 requires-python 约束。
2. 使用 --clear 标志重建虚拟环境：

   uv venv --clear --python 3.12

   这会让 uv 自动删除旧的 .venv 目录，并用指定的 Python 版本创建一个全新的环境。

总结

场景	是否必须手动删除 .venv？
补丁版本升级 (如 3.12.4 → 3.12.6)	否，uv 可自动处理。
次要/主要版本更换 (如 3.11 → 3.12)	是，通常需要重建。但推荐使用 uv venv --clear 来自动完成。

所以，你听到的“必须删 .venv”的说法，更准确地说是针对更换 Python 大版本这一特定场景的过时经验。现在，使用 --clear 是更符合 uv 设计理念的做法。

虽然这么说，但是好像一般都是切换大版本的吧

Andrea

[Bash shell] 纯文本查看 复制代码

export UV_CACHE_DIR=/data/uv_env/cache
export UV_PYTHON_INSTALL_DIR=/data/uv_env/python
export UV_DEFAULT_INDEX=https://mirrors.huaweicloud.com/repository/pypi/simple
export UV_PYTHON_INSTALL_MIRROR=https://gh-proxy.com/https://github.com/astral-sh/python-build-standalone/releases/download/

补充几个环境变量吧，分别是缓存存放位置、Python安装包的位置、默认pip国内源的位置（我这里华为的源比较快）、安装包下载加速（默认GitHub可能网络会限制住，原理就是给github套个代理）。这里Linux环境的，Windows的话，对应去系统环境变量里面配置，键值对的方式配置即可。