Windows下uv安装与环境配置教程

文章目录

• 一、为什么选择 uv
• • 1、传统 Python 环境管理的痛点
  • 2、本文最终要完成什么
• 二、安装 uv
• • 1、使用官方安装脚本
  • 2、将 uv 加入 Path
  • 3、验证安装结果
• 三、规划 uv 的数据目录
• • 1、四个目录分别保存什么
  • 2、使用 PowerShell 一次完成配置
• 四、使用 uv 安装 Python 3.10.18
• • 1、安装指定版本
  • 2、检查 Python 是否安装成功
• 五、为项目创建独立环境
• • 1、先认识三个核心文件
  • 2、固定项目的 Python 版本
  • 3、根据锁文件同步依赖
  • 4、验证环境是否真正可用
• 六、在 PyCharm 中选择正确的解释器
• • 1、uv 配置完成后为什么还要选择解释器
  • 2、Notebook 还要检查内核
• 七、常见问题与解决方法
• • 1、输入 uv 后提示找不到命令
  • 2、刚创建的 cache、python 和 tools 都是空的
  • 3、PyCharm 提示 No module named pip
  • 4、程序可以运行，但编辑器仍然标红
  • 5、为什么不应该复制别人的 .venv
• 八、常用命令速查
• • 1、Python 与项目管理
  • 2、运行项目
• 九、总结

一、为什么选择 uv

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

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

python –m venv .venv
.\\.venv\\Scripts\\Activate.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:\\UVProgram\\uv\\bin

可以按 Win + R，输入：

sysdm.cpl

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

3、验证安装结果

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

执行：

uv —version

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

where.exe uv

本文的预期路径是：

D:\\UVProgram\\uv.exe

三、规划 uv 的数据目录

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

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

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

2、使用 PowerShell 一次完成配置

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

$uvProgram = "D:\\UVProgram"
$uvData = "$uvProgram\\uv"
$uvBin = "$uvData\\bin"

New-Item –ItemType Directory –Force –Path `
$uvBin, `
"$uvData\\cache", `
"$uvData\\python", `
"$uvData\\tools" | Out-Null

[Environment]::SetEnvironmentVariable(
"UV_INSTALL_DIR", $uvProgram, "User"
)
[Environment]::SetEnvironmentVariable(
"UV_CACHE_DIR", "$uvData\\cache", "User"
)
[Environment]::SetEnvironmentVariable(
"UV_PYTHON_INSTALL_DIR", "$uvData\\python", "User"
)
[Environment]::SetEnvironmentVariable(
"UV_PYTHON_BIN_DIR", $uvBin, "User"
)
[Environment]::SetEnvironmentVariable(
"UV_TOOL_DIR", "$uvData\\tools", "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 和 uv.lock，就不需要重新执行 uv init，不要随意修改老师锁定的依赖版本。

2、固定项目的 Python 版本

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

Set-Location "D:\\Jupyter_Projects\\PythonProject\\大模型学习\\modelchat"

然后执行：

uv python pin 3.10.18

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

3.10.18

3、根据锁文件同步依赖

继续在项目根目录执行：

uv sync —locked

这条命令会完成四件事：

–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，因此仍需要关联一次项目解释器：

项目根目录\\.venv\\Scripts\\python.exe

本文对应的路径是：

D:\\Jupyter_Projects\\PythonProject\\大模型学习\\modelchat\\.venv\\Scripts\\python.exe

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

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

Python 3.10 (modelchat)

2、Notebook 还要检查内核

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

import sys
print(sys.executable)

正确结果应指向：

项目根目录\\.venv\\Scripts\\python.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 解释器的完整配置。

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

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