uv 作为 Python 项目管理工具的使用笔记

最近在学习黑马的 LangChain 教程，项目管理工具用到了 uv。这里整理一下 uv 的基础使用方法，以及在 Windows / PyCharm 里容易遇到的问题。

一、uv 是什么？

uv 是一个 Python 项目管理工具，可以用来：

• 创建 Python 项目
• 创建虚拟环境
• 安装和删除依赖
• 管理 pyproject.toml
• 生成 uv.lock
• 在虚拟环境中运行 Python 程序

可以简单理解为：

uv ≈ pip + venv + 项目依赖管理工具

相比传统的 pip install，uv 更适合用来管理一个完整的 Python 项目。

---

二、安装 uv

Windows 下安装后，uv 的路径一般类似：

C:\Users\用户名\.local\bin\uv.exe

安装完成后，可以查看版本：

uv --version

如果能正常输出版本号，说明安装成功。

---

三、设置 uv 镜像源

为了加快国内下载速度，可以设置清华源：

setx UV_DEFAULT_INDEX "https://pypi.tuna.tsinghua.edu.cn/simple"

设置后建议重新打开一个终端。

也可以检查环境变量是否生效：

echo $env:UV_DEFAULT_INDEX

---

四、创建 Python 项目

创建一个新项目：

uv init langchain-demo

进入项目目录：

cd langchain-demo

如果想指定 Python 版本，例如 Python 3.11：

uv init langchain-demo --python 3.11

或者在当前目录初始化项目：

uv init --python 3.11

---

五、创建虚拟环境

在项目目录下执行：

uv venv

会生成一个 .venv 目录，这就是当前项目的虚拟环境。

---

六、是否必须手动激活虚拟环境？

不一定。

如果使用 uv 管理项目，很多情况下不需要手动激活虚拟环境。

比如安装依赖：

uv add langchain

运行代码：

uv run python main.py

uv 会自动使用当前项目的 .venv 虚拟环境。

推荐用法：

uv add 包名
uv run python 文件名.py

---

七、安装项目依赖

例如安装 LangChain：

uv add langchain

执行后，uv 会自动更新两个文件：

pyproject.toml
uv.lock

其中：

pyproject.toml

记录项目依赖，比如项目需要 langchain。

uv.lock

锁定具体依赖版本，保证以后别人安装出来的环境一致。

---

八、删除依赖

如果不需要某个包，可以执行：

uv remove langchain

这样会从项目依赖中移除它，并更新相关配置文件。

---

九、同步依赖

如果你拿到一个已有项目，里面有：

pyproject.toml
uv.lock

可以直接执行：

uv sync

它会根据项目配置自动安装所有依赖。

---

十、运行 Python 文件

假设项目里有一个 main.py：

uv run python main.py

这样会在当前项目虚拟环境中运行代码。

不需要提前执行：

.venv\Scripts\activate

---

十一、PyCharm 终端激活虚拟环境报错

在 PyCharm 中，如果终端显示类似：

MINGW64

说明你用的是 Git Bash。

这时候不能使用 PowerShell 的写法：

.venv\Scripts\activate

否则可能报错：

bash: .venvScriptsactivate: command not found

原因是 Git Bash 会把反斜杠 \ 当成转义符。

Git Bash 中应该这样激活：

source .venv/Scripts/activate

或者：

. .venv/Scripts/activate

如果是 PowerShell，应该使用：

.venv\Scripts\Activate.ps1

如果是 CMD，应该使用：

.venv\Scripts\activate.bat

---

十二、不要把项目放在 System32 目录

如果在 PowerShell 中执行：

uv add langchain

出现类似错误：

failed to create file `C:\Windows\System32\langchain-demo\pyproject.toml`
拒绝访问。 (os error 5)

说明当前项目在：

C:\Windows\System32\langchain-demo

这是 Windows 系统目录，普通用户没有权限写入文件。

建议把项目放到用户目录下，例如：

C:\Users\serendipity\Projects\langchain-demo

推荐创建方式：

mkdir C:\Users\serendipity\Projects
cd C:\Users\serendipity\Projects
uv init langchain-demo --python 3.11
cd langchain-demo
uv add langchain

---

十三、常用命令总结

创建项目：

uv init 项目名

指定 Python 版本创建项目：

uv init 项目名 --python 3.11

创建虚拟环境：

uv venv

添加依赖：

uv add 包名

删除依赖：

uv remove 包名

同步依赖：

uv sync

运行 Python 文件：

uv run python main.py

查看版本：

uv --version

---

十四、推荐工作流程

以 LangChain 项目为例：

cd C:\Users\serendipity\Projects
uv init langchain-demo --python 3.11
cd langchain-demo
uv add langchain
uv run python main.py

以后安装依赖，尽量使用：

uv add 包名

运行代码，尽量使用：

uv run python 文件名.py

这样可以避免虚拟环境没激活、依赖装错位置等问题。