uv入门笔记

最近在学习 Python 项目管理时，我认识了一个新工具：uv。

一开始我对它的理解比较模糊，因为我之前更熟悉的是 conda：创建环境、安装包、切换环境，基本都是 conda create、conda activate、conda install 这一套。

但真正试了一下 uv 之后，我发现它和 conda 的思路并不完全一样。uv 更像是面向 Python 项目的现代工具链，而 conda 更像是一个跨语言、跨平台的环境和包管理系统。

这篇文章主要记录我对 uv 的理解，包括：

• uv 是什么
• uv 和 conda 有什么区别
• Windows 下如何把 uv 安装到 D 盘
• uv 的核心概念
• uv add、uv pip install、uv run 的区别
• uv 的一些常用命令

一、什么是 uv

uv 是 Astral 开发的一个开源 Python 包和项目管理工具，项目地址在 GitHub：

https://github.com/astral-sh/uv

官方对 uv 的描述是：一个用 Rust 编写的、速度非常快的 Python package and project manager。

它可以用来替代很多 Python 开发中常见的工具，比如：

• pip
• pip-tools
• pipx
• poetry
• pyenv
• virtualenv

也就是说，uv 不只是一个"装包工具"，它还可以创建项目、管理依赖、创建虚拟环境、管理 Python 版本、运行项目脚本等。

官方文档：

https://docs.astral.sh/uv/

二、uv 和 conda 有什么区别

我一开始最疑惑的地方就是：既然 conda 已经能创建环境、安装库，为什么还需要 uv？

简单理解：

uv：更偏 Python 项目管理
conda：更偏跨语言环境管理

对比项	uv	conda
主要定位	Python 包和项目管理工具	包、依赖和环境管理工具
包来源	主要来自 PyPI	主要来自 conda channels，如 conda-forge
环境方式	通常在项目目录下创建 .venv	通常在 conda 的 envs 目录下创建环境
是否只面向 Python	基本围绕 Python 生态	可以管理 Python、R、C/C++、CUDA 等
项目依赖文件	pyproject.toml、uv.lock	environment.yml
适合场景	普通 Python 项目、Web、脚本、CLI、库开发	数据科学、机器学习、CUDA、复杂二进制依赖

conda 官方文档中说，conda 提供的是"任意语言"的包、依赖和环境管理：

https://docs.conda.io/

所以我的理解是：

如果只是普通 Python 项目，比如爬虫、FastAPI、LangChain、小工具脚本，用 uv 会很舒服。

如果项目依赖 CUDA、PyTorch 指定 CUDA 版本、GDAL、MKL、R 语言等复杂底层依赖，conda 仍然很有价值。

三、uv 的核心概念

学习 uv 时，我觉得最重要的是先分清楚几个概念。

很多初学者容易把"uv 安装在哪里"和"Python 库安装在哪里"混在一起。实际上，这些东西不是一回事。

1. uv 工具本体

uv 本体就是 uv.exe、uvx.exe、uvw.exe 这些可执行文件。

如果把 uv 安装到：

D:\uv

那么这个目录下通常会看到：

D:\uv\
  uv.exe
  uvx.exe
  uvw.exe

这个目录只是 uv 工具本身的位置。

它不等于项目依赖安装目录。

2. uv 缓存目录

uv 下载依赖、构建包、复用安装内容时，会使用缓存目录。

这个目录可以通过环境变量指定：

setx UV_CACHE_DIR "D:\uv\cache"

设置后，可以用下面命令查看：

uv cache dir

需要注意：设置环境变量不会立刻创建文件夹。只有当 uv 真正使用缓存时，目录才可能出现。也可以手动创建：

mkdir D:\uv\cache

3. uv 管理的 Python 目录

uv 可以安装和管理 Python 版本，比如：

uv python install 3.12

这些由 uv 管理的 Python 可以通过 UV_PYTHON_INSTALL_DIR 指定安装位置：

setx UV_PYTHON_INSTALL_DIR "D:\uv\python"

查看目录：

uv python dir

4. 项目的 .venv

这是最关键的概念。

uv 给项目安装依赖时，通常会在项目目录下创建 .venv：

myproj\
  .venv\
  pyproject.toml
  uv.lock

如果项目在 D 盘：

D:\projects\myproj

那么依赖通常安装到：

D:\projects\myproj\.venv\Lib\site-packages

如果项目在 C 盘：

C:\Users\你的用户名\myproj

那么依赖通常安装到：

C:\Users\你的用户名\myproj\.venv\Lib\site-packages

所以结论是：

uv 本体放在哪里，不决定项目依赖放在哪里。
项目依赖通常跟着项目目录走。

5. pyproject.toml

pyproject.toml 是现代 Python 项目常用的配置文件。

uv 会把项目依赖记录在这个文件中，比如：

[project]
dependencies = [
    "requests",
    "notebook",
]

当我们执行：

uv add notebook

uv 会把 notebook 写入 pyproject.toml。

6. uv.lock

uv.lock 是锁文件。

pyproject.toml 记录的是项目需要什么依赖，而 uv.lock 会记录具体安装了哪些版本。

比如项目中写的是：

requests

但锁文件中会记录具体版本，以及它依赖的其他包版本。

这样做的好处是：别人拿到你的项目后执行：

uv sync

就可以尽量复现和你一致的环境。

四、Windows 下把 uv 安装到 D 盘

官方 Windows 安装方式是：

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

官方安装说明：

https://docs.astral.sh/uv/getting-started/installation/

如果直接这样安装，uv 默认会安装到用户可执行目录。Windows 上通常会在 C 盘用户目录下，比如：

C:\Users\你的用户名\.local\bin

但我不想把 uv 放在 C 盘，所以我在 D 盘创建了一个目录：

D:\uv

然后使用 UV_INSTALL_DIR 指定安装位置：

powershell -ExecutionPolicy ByPass -c {$env:UV_INSTALL_DIR = "D:\uv"; irm https://astral.sh/uv/install.ps1 | iex}

安装完成后，D:\uv 目录下会有类似这些文件：

uv.exe
uvx.exe
uvw.exe

然后需要把 D:\uv 加入系统环境变量 Path。

可以通过图形界面设置：

系统属性 -> 高级系统设置 -> 环境变量 -> 用户变量 -> Path -> 新建 -> D:\uv

重新打开 PowerShell 后，检查是否安装成功：

uv --version

如果想查看 uv 的实际路径，PowerShell 里建议用：

where.exe uv

或者：

Get-Command uv

注意：PowerShell 里的 where 可能是 Where-Object 的别名，所以直接输入 where uv 不一定有输出。

五、把 uv 的缓存、Python、工具目录也放到 D 盘

UV_INSTALL_DIR 只控制 uv.exe 安装在哪里。uv 的缓存、Python 安装目录、工具目录是另外的。

我希望这些内容也放在 D:\uv 下面，于是设置：

setx UV_CACHE_DIR "D:\uv\cache"
setx UV_PYTHON_INSTALL_DIR "D:\uv\python"
setx UV_TOOL_DIR "D:\uv\tools"

设置完成后，需要重新打开 PowerShell。

然后可以检查：

uv cache dir
uv python dir
uv tool dir

需要注意，setx 只是设置环境变量，不会立刻创建文件夹。文件夹可能要等 uv 真正使用时才会出现，也可以手动创建：

mkdir D:\uv\cache
mkdir D:\uv\python
mkdir D:\uv\tools

相关官方文档：

• 环境变量：https://docs.astral.sh/uv/reference/environment/
• 存储位置：https://docs.astral.sh/uv/reference/storage/
• 自定义安装路径：https://docs.astral.sh/uv/reference/installer/

六、uv add、uv pip install、uv run 的区别

这三个命令很常见，但它们的作用不一样。

1. uv add

uv add 是项目级别的依赖管理命令。

例如：

uv add notebook

它通常会做几件事：

• 把 notebook 写入 pyproject.toml
• 更新 uv.lock
• 把依赖安装到当前项目的 .venv

也就是说，uv add 不只是"安装一个包"，它还会修改项目的依赖配置。

适合在正式项目中添加依赖。

例如：

uv add requests
uv add notebook
uv add opencv-python

添加开发依赖可以用：

uv add --dev pytest

2. uv pip install

uv pip install 更像是 uv 提供的 pip 兼容命令。

例如：

uv pip install requests

它的感觉更接近传统的：

pip install requests

区别是 uv 的速度通常更快。

但是要注意：uv pip install 主要是直接往某个 Python 环境里安装包，它不一定会像 uv add 那样维护项目的 pyproject.toml。

所以我的理解是：

做正式项目：优先使用 uv add
临时实验或兼容 pip 工作流：可以使用 uv pip install

3. uv run

uv run 用来在 uv 管理的项目环境中运行命令。

比如运行 Python：

uv run python

运行脚本：

uv run python main.py

启动 Jupyter Notebook：

uv run jupyter notebook

它的好处是：即使你没有手动激活 .venv，uv 也会帮你在项目环境中运行命令。

例如项目在：

D:\the_langchain

你执行：

cd D:\the_langchain
uv add notebook
uv run jupyter notebook

这里启动的就是当前项目环境里的 Jupyter。

可以用下面命令确认当前使用的是哪个 Python：

uv run python -c "import sys; print(sys.executable)"

如果输出类似：

D:\the_langchain\.venv\Scripts\python.exe

说明 uv 使用的是项目目录下的 .venv。

4. 三者简单对比

命令	作用	是否修改项目依赖文件	常见使用场景
uv add 包名	添加项目依赖	会修改 pyproject.toml 和 uv.lock	正式项目添加依赖
uv pip install 包名	兼容 pip 的安装方式	通常不作为项目依赖管理方式	临时安装、兼容旧工作流
uv run 命令	在项目环境中运行命令	不一定修改依赖	运行脚本、启动工具

七、和 conda 的使用习惯对比

如果以前习惯 conda，刚开始用 uv 时会有一点不适应。

conda 的核心习惯是：

我现在激活了哪个环境？

uv 的核心习惯更像是：

我现在在哪个项目目录？

1. conda 的常见流程

以前使用 conda 时，我可能会这样做：

conda create -n myproj python=3.11
conda activate myproj
conda install requests
python main.py

这个流程的重点是先创建并激活一个环境。

之后安装包、运行 Python，都依赖当前激活的 conda 环境。

2. uv 的常见流程

使用 uv 时，我更常这样做：

uv init myproj
cd myproj
uv add requests
uv run python main.py

这个流程的重点是项目目录。

依赖会记录到项目配置中，并安装到项目自己的 .venv。

3. 命令习惯对照

需求	conda	uv
创建环境或项目	conda create -n demo python=3.11	uv init demo
激活环境	conda activate demo	通常不需要手动激活，使用 uv run
添加依赖	conda install requests 或 pip install requests	uv add requests
添加开发依赖	常见做法是单独维护 requirements 文件	uv add --dev pytest
运行脚本	python main.py	uv run python main.py
导出环境	conda env export > environment.yml	pyproject.toml + uv.lock
同步环境	conda env update -f environment.yml	uv sync
查看 Python 路径	where python / python -c ...	uv run python -c "import sys; print(sys.executable)"

4. 思维方式上的区别

conda 更像是先创建一个环境，然后在这个环境里做事情。

uv 更像是先进入一个项目，然后围绕这个项目管理依赖和运行命令。

这也是为什么 uv 项目里经常会看到：

pyproject.toml
uv.lock
.venv

而 conda 项目里更常看到：

environment.yml

5. conda 和 uv 可以混用吗

可以，但要注意分工。

一种常见方式是：

conda create -n mybase python=3.11
conda activate mybase
uv init myproj
cd myproj
uv add requests

但是混用时要明白：conda 和 uv 都可能管理 Python 包，如果随意混着装，后期可能不容易判断某个包到底是由谁管理的。

我个人更倾向于：

conda：负责复杂底层环境，比如 CUDA、GDAL、R、特定科学计算依赖
uv：负责普通 Python 项目的依赖管理

对于普通 Python 项目，直接用 uv 会更清爽。

八、uv 常用命令

创建新项目：

uv init myproj

在当前目录初始化项目：

uv init

添加依赖：

uv add requests
uv add notebook
uv add opencv-python

添加开发依赖：

uv add --dev pytest

删除依赖：

uv remove requests

运行 Python：

uv run python

运行脚本：

uv run python main.py

同步环境：

uv sync

查看依赖树：

uv tree

安装 Python 版本：

uv python install 3.12

查看 uv 管理的 Python 目录：

uv python dir

查看缓存目录：

uv cache dir

清理缓存：

uv cache clean

更新 uv：

uv self update

官方 CLI 命令参考：

https://docs.astral.sh/uv/reference/cli/

九、常见问题和踩坑记录

1. cd D:\uv 后安装，uv 会自动安装到当前目录吗

不会。

当前目录不决定 uv 的安装位置。

如果想把 uv 安装到 D 盘，需要使用：

$env:UV_INSTALL_DIR = "D:\uv"

或者：

powershell -ExecutionPolicy ByPass -c {$env:UV_INSTALL_DIR = "D:\uv"; irm https://astral.sh/uv/install.ps1 | iex}

2. where uv 为什么没有输出

在 PowerShell 里，where 可能是 Where-Object 的别名。

建议使用：

where.exe uv

或者：

Get-Command uv

3. setx 后为什么文件夹没有出现

因为 setx 只是设置环境变量，不会自动创建文件夹。

比如：

setx UV_CACHE_DIR "D:\uv\cache"

只是告诉系统以后 uv 的缓存目录用这里。

如果想马上看到目录，可以手动创建：

mkdir D:\uv\cache

4. uv add opencv 可以吗

通常不这样写。

OpenCV 在 PyPI 上常用包名是：

uv add opencv-python

安装后在 Python 中导入：

import cv2

如果不需要 GUI 功能，也可以考虑：

uv add opencv-python-headless

5. conda 环境激活时可以用 uv 吗

可以。

比如终端前面显示：

(base) (the_langchain) PS D:\the_langchain>

这说明当前可能激活着 conda 环境。

但如果在 D:\the_langchain 中执行：

uv add notebook

uv 通常会把依赖安装到当前项目的：

D:\the_langchain\.venv

可以用下面命令确认：

uv run python -c "import sys; print(sys.executable)"

如果输出是：

D:\the_langchain\.venv\Scripts\python.exe

说明 uv 使用的是项目自己的虚拟环境。

十、我的理解总结

如果你以前熟悉 conda，可以先这样理解 uv：

conda activate xxx
conda install xxx

更像是在操作某个全局环境。

而 uv 的思路更像是：

我进入哪个项目目录，就管理哪个项目的依赖。

uv 会把项目依赖写入 pyproject.toml，把具体版本锁定到 uv.lock，并把真正安装的库放在项目目录下的 .venv 中。

所以对我来说，uv 最重要的几个位置是：

D:\uv                 uv 工具本体
D:\uv\cache           uv 缓存
D:\uv\python          uv 管理的 Python
D:\uv\tools           uv 安装的命令行工具
D:\projects\xxx\.venv 某个项目自己的依赖环境

一句话总结：

uv 是一个非常适合 Python 项目开发的现代工具；
conda 更适合管理复杂科学计算环境；
uv 装在哪里不重要，项目放在哪里，依赖通常就跟在哪里。