Windows下uv安装与环境配置的超完整教程

一、为什么选择 uv

1、传统 Python 环境管理的痛点

刚接触 Python 项目时，我们通常会依次安装 Python、创建虚拟环境、激活环境，再使用 pip 安装依赖：

python -m venv .venv
..venvScriptsActivate.ps1
pip install -r requirements.txt

这套流程可以使用，但项目一多，就容易遇到下面的问题：

• 不同项目要求的 Python 版本不同；
• 虚拟环境建好了，IDE 却选中了另一个解释器；
• requirements.txt 只记录直接依赖，换电脑后版本可能不完全一致；
• 下载大量依赖耗时较长，多个项目还会重复下载；
• pip、虚拟环境和 Python 版本需要分别管理。

uv 将 Python 版本、虚拟环境、依赖和锁文件统一到了一套工作流中。拿到包含 pyproject.toml 和 uv.lock 的项目后，通常只需要：

uv python pin 3.10.18
uv sync --locked

uv 就会选择指定的 Python、创建项目专属的 .venv，并按照锁文件安装准确版本的依赖。

2、本文最终要完成什么

本文使用的环境如下：

操作系统：Windows 11
终端：Windows PowerShell
uv：0.11.31
Python：3.10.18
开发工具：PyCharm

最终目录规划为：

D:UVProgram
├─ uv.exe
├─ uvx.exe
├─ uvw.exe
└─ uv
   ├─ bin
   ├─ cache
   ├─ python
   └─ tools

其中，uv 程序、Python、缓存和工具都放在 D 盘，系统盘不会因为后续学习多个项目而持续增长。

二、安装 uv

1、使用官方安装脚本

在 PowerShell 中可以执行官方安装命令：

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

也可以通过 Windows 包管理器安装：

winget install --id=astral-sh.uv -e

如果已经从 uv 发布页面获得了 uv.exe、uvx.exe 和 uvw.exe，也可以直接解压使用。本文采用的就是这种方式，三个文件放在：

D:UVProgram

uv 是独立可执行程序，不需要再通过传统安装向导安装。

2、将 uv 加入 Path

仅仅把 uv.exe 放进文件夹还不够。Windows 必须知道去哪里寻找 uv 命令，因此需要把下面的目录加入当前用户的 Path：

D:UVProgram
D:UVProgramuvbin

可以按 Win + R，输入：

sysdm.cpl

然后依次进入“高级”→“环境变量”→“用户变量”→“Path”进行添加。

3、验证安装结果

修改环境变量后，要关闭已经打开的 PowerShell 和 PyCharm，再重新打开。旧进程不会自动读取刚刚写入的环境变量。

执行：

uv --version

只要能够正常显示版本号，就说明 uv 已经可以使用。还可以检查 Windows 实际调用的是哪个文件：

where.exe uv

本文的预期路径是：

D:UVProgramuv.exe

三、规划 uv 的数据目录

1、四个目录分别保存什么

为了便于维护，我在 D:UVProgramuv 下建立了四个目录：

目录	用途
bin	保存 uv 管理的命令入口
cache	保存 Python 和依赖包的下载缓存
python	保存 uv 安装的 Python 版本
tools	保存通过 uv tool install 安装的独立工具

用于下载 Python、安装依赖或安装工具等内容到对应目录中。

2、使用 PowerShell 一次完成配置

下面的命令会创建目录、写入用户环境变量，并补充用户 Path。如果你的安装位置不同，只需要修改第一行。

$uvProgram = "D:UVProgram"
$uvData = "$uvProgramuv"
$uvBin = "$uvDatabin"

New-Item -ItemType Directory -Force -Path `
    $uvBin, `
    "$uvDatacache", `
    "$uvDatapython", `
    "$uvDatatools" | Out-Null

[Environment]::SetEnvironmentVariable(
    "UV_INSTALL_DIR", $uvProgram, "User"
)
[Environment]::SetEnvironmentVariable(
    "UV_CACHE_DIR", "$uvDatacache", "User"
)
[Environment]::SetEnvironmentVariable(
    "UV_PYTHON_INSTALL_DIR", "$uvDatapython", "User"
)
[Environment]::SetEnvironmentVariable(
    "UV_PYTHON_BIN_DIR", $uvBin, "User"
)
[Environment]::SetEnvironmentVariable(
    "UV_TOOL_DIR", "$uvDatatools", "User"
)
[Environment]::SetEnvironmentVariable(
    "UV_TOOL_BIN_DIR", $uvBin, "User"
)

$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
$pathItems = @($userPath -split ";" | Where-Object { $_ })

if ($pathItems -notcontains $uvProgram) {
    $pathItems += $uvProgram
}
if ($pathItems -notcontains $uvBin) {
    $pathItems += $uvBin
}

[Environment]::SetEnvironmentVariable(
    "Path", ($pathItems -join ";"), "User"
)

Write-Host "配置完成，请关闭终端后重新打开。" -ForegroundColor Green

这里需要注意：UV_INSTALL_DIR 主要决定 uv 安装程序存放可执行文件的位置；缓存、Python 和工具目录则分别由其他变量控制。

四、使用 uv 安装 Python 3.10.18

1、安装指定版本

重新打开 PowerShell，执行：

uv python install 3.10.18

安装成功后会出现类似结果：

Installed Python 3.10.18
+ cpython-3.10.18-windows-x86_64-none

初次安装时，系统得从网络抓取 Python 环境，耗时十几秒乃至更久都是常态。老师那边秒装完成，无非是网络环境更优，或者本地缓存里已经有了现成的文件，这并不代表你的操作出了什么岔子，不必因此焦虑。

2、检查 Python 是否安装成功

查看已经安装的版本：

uv python list --only-installed

查找 Python 3.10.18 的实际位置：

uv python find 3.10.18

这里安装的是由 uv 管理的 Python，不需要把它当作普通 Python 安装包再执行一次安装程序。

五、为项目创建独立环境

1、先认识三个核心文件

一个使用 uv 管理的项目通常会包含：

文件	作用
pyproject.toml	声明项目基本信息、Python 要求和直接依赖
uv.lock	锁定直接依赖和间接依赖的准确版本
.python-version	指定当前项目使用的 Python 版本

如果老师已经提供了 pyproject.toml 和 uv.lock，就不需要重新执行 uv init，不要随意修改老师锁定的依赖版本。

2、固定项目的 Python 版本

先进入项目根目录。本文的项目目录为：

Set-Location "D:Jupyter_ProjectsPythonProject大模型学习modelchat"

然后执行：

uv python pin 3.10.18

这条命令会在项目根目录生成 .python-version，文件内容只有：

3.10.18

3、根据锁文件同步依赖

继续在项目根目录执行：

uv sync --locked

这条命令会完成四件事：

1. 检查 pyproject.toml 与 uv.lock 是否一致；
2. 自动创建项目目录下的 .venv；
3. 选择 Python 3.10.18；
4. 按照锁文件安装准确版本的全部依赖。

--locked 表示不允许在同步过程中偷偷更新锁文件。如果项目声明与锁文件不一致，uv 会直接提示错误，这有助于保证学生和老师使用同一套环境。

第一次同步时，终端可能连续显示很多绿色的 + 和包名。这表示依赖正在安装。

uv 默认执行“精确同步”：不在项目依赖声明中的额外包可能会被移除。因此，日常应优先通过 pyproject.toml、uv add 和 uv sync 管理项目依赖。

4、验证环境是否真正可用

检查项目使用的 Python：

uv run python --version

预期结果：

Python 3.10.18

再验证课程中会使用的主要依赖：

uv run python -c "import streamlit, langchain, openai; print('环境配置成功')"

如果输出：

环境配置成功

说明 Python、虚拟环境和依赖都已经可以正常使用。

六、在 PyCharm 中选择正确的解释器

1、uv 配置完成后为什么还要选择解释器

uv 负责创建和维护运行环境，PyCharm 负责编辑、分析和运行代码。两者分工不同。

即使 .venv 已经创建成功，PyCharm 也不一定知道当前项目应该使用哪个 Python，因此仍需要关联一次项目解释器：

项目根目录.venvScriptspython.exe

本文对应的路径是：

D:Jupyter_ProjectsPythonProject大模型学习modelchat.venvScriptspython.exe

在 PyCharm 中进入“设置”→“Python”→“解释器”→“添加解释器”→“添加本地解释器”，选择“现有环境”，再定位到上面的文件。

配置完成后，右下角应显示类似：

Python 3.10 (modelchat)

2、Notebook 还要检查内核

打开 .ipynb 后，Notebook 使用的内核也应该来自项目 .venv。可以在单元格中运行：

import sys
print(sys.executable)

正确结果应指向：

项目根目录.venvScriptspython.exe

PyCharm 界面中的“IDE 托管服务器（Auto）”指的是 Jupyter 服务连接方式，不等于 Python 解释器本身。

七、常见问题与解决方法

1、输入 uv 后提示找不到命令

先临时把 uv 加入当前 PowerShell：

$env:Path = "D:UVProgram;$env:Path"
uv --version

如果这样可以运行，说明 uv 本身没有问题，真正的原因是用户 Path 没有配置正确，或者修改环境变量后没有重启终端。

2、刚创建的 cache、python 和 tools 都是空的

这是正常现象。文件夹只是预先规划的存储位置：

• 安装 Python 后，python 才会出现内容；
• 下载 Python 或依赖后，cache 才会出现内容；
• 使用 uv tool install 后，tools 才会出现内容。

空文件夹不代表配置失败。

3、PyCharm 提示 No module named pip

uv 自己能够安装依赖，所以 uv 创建的环境不一定预装 pip。但部分 PyCharm 版本的软件包管理界面仍会调用 pip，此时可在项目根目录执行：

uv pip install pip

这是一项 IDE 兼容措施，不是 uv 正常工作的必要条件。并且由于 uv sync 默认采用精确同步，后续再次同步时，未声明在项目中的 pip 可能被移除。

4、程序可以运行，但编辑器仍然标红

这种情况通常不是运行环境错误，而是 PyCharm 的代码索引尚未更新。

先在 PyCharm 终端执行：

python -c "import sys, langchain_openai; print(sys.executable); print(langchain_openai.__file__)"

如果输出结果指向项目里的 .venv，并且代码也能正常跑起来，那基本就可以判断：依赖已经装好了。接下来可以重新选择解释器，等索引跑完；要是还有异常，再考虑使用 PyCharm 的“使缓存失效并重启”。

不要为了消除红线随意升级老师锁定的依赖，否则可能让代码和课程环境产生版本差异。

5、为什么不应该复制别人的 .venv

.venv 中可能包含原电脑和原项目的绝对路径，直接复制或移动后容易失效。

真正应该保存和传递的是：

pyproject.toml
uv.lock
.python-version

换电脑或移动项目后，在新的项目目录重新执行：

uv sync --locked

这也是锁文件存在的意义：传递环境说明，而不是传递一整个虚拟环境文件夹。

八、常用命令速查

1、Python 与项目管理

# 查看 uv 版本
uv --version

# 安装指定 Python
uv python install 3.10.18

# 查看已安装的 Python
uv python list --only-installed

# 为当前项目固定 Python
uv python pin 3.10.18

# 按锁文件同步项目
uv sync --locked

# 查看依赖树
uv tree

2、运行项目

# 查看项目环境中的 Python 版本
uv run python --version

# 运行普通 Python 文件
uv run python main.py

# 启动 Streamlit
uv run streamlit run main.py

# 启动 Jupyter Lab
uv run jupyter lab

uv run 会在执行命令前检查项目环境，因此平时即使不手动激活 .venv，也能确保命令在正确的环境中运行。

九、总结

本文完成了 Windows 11 下 uv、Python 3.10.18、项目虚拟环境和 PyCharm 解释器的完整配置。

整个过程最值得记住的是：

1. uv.exe 所在目录必须加入 Path；
2. 每个项目应拥有独立的 .venv；
3. .python-version 用于固定 Python 版本；
4. pyproject.toml 用于声明项目依赖；
5. uv.lock 用于锁定完整依赖版本；
6. 已有锁文件时优先执行 uv sync --locked；
7. PyCharm 需要关联项目的 .venvScriptspython.exe；
8. 不要复制别人的 .venv，应在本机通过锁文件重新同步。

完成这套基础环境后，后续学习 LangChain、RAG、Streamlit 和 Agent 时，就可以继续复用同一套 uv 工作流，同时让不同项目的依赖彼此隔离。