Python包管理器：uv

原创已于 2025-11-25 20:44:32 修改 · 1k 阅读

3 ·

CC 4.0 BY-SA版权

文章标签：

#python #uv #开发语言

于 2025-05-23 15:14:36 首次发布

编程学习笔记专栏收录该内容

190 篇文章

订阅专栏

诸神缄默不语-个人技术博文与视频目录

我用这个包是因为同事推荐了，所以我来尝试用下，发现我超真的好快！
我之前一般用conda或pip（大部分Python程序员应该都这样），uv能够很好的迅速迁移。

官网：https://docs.astral.sh/uv/

文章目录

1. 安装
2. uv项目介绍
3. Python版本管理
4. 新建uv项目
5. uv + Jupyter Notebook
6. 对一个现成的pip管理的Python项目，用uv无缝衔接pip命令进行管理
7. 本文撰写过程中参考的其他网络资料

1. 安装

不需要预先安装Python环境，直接装uv就行。

Windows系统用powershell装：powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

在这里插入图片描述

注意如果在VSCode中执行后续命令的话，需要先把VSCode重启一下，让.local\bin这个文件夹加到路径中。

2. uv项目介绍

uv的一个项目文件夹组成部分是：

.
├── .venv
│   ├── bin
│   ├── lib
│   └── pyvenv.cfg
├── .python-version
├── README.md
├── main.py
├── pyproject.toml
└── uv.lock

pyproject.toml包含项目元信息，如：

[project]
name = "hello-world"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
dependencies = []

这个文件可以直接改，也可以用uv add uv remove这类命令来改。

uv.lock可读但不可编辑，由uv维护。

3. Python版本管理

https://docs.astral.sh/uv/guides/install-python/

如果没有安装Python环境，直接用uv python install就可以：
在这里插入图片描述

如果已安装Python环境，uv会自动从Path中找到Python路径。
其他情况我以后再补。

4. 新建uv项目

uv init example（example是项目名）

uv会新建这几个文件：

├── .gitignore
├── .python-version
├── README.md
├── main.py
└── pyproject.toml

main.py包含了一个Hello Word代码，可以用uv run example\main.py运行，输出Hello from example!

如果已经有了一个现成的Python代码文件夹，可以直接在项目下运行uv init，新生成的文件是一样的。

4.1 更新环境变量UV_CACHE_DIR

这是遇到了这个警告信息：

warning: Failed to hardlink files; falling back to full copy. This may lead to degraded performance.               
         If the cache and target directories are on different filesystems, hardlinking may not be supported.       
         If this is intentional, set `export UV_LINK_MODE=copy` or use `--link-mode=copy` to suppress this warning.

大意就是说因为缓存和项目文件夹不在同一个文件系统所以不能硬链接，所以会导致运行变慢。参考Failed to hardlink files: Issue with ruff cache · Issue #7285 · astral-sh/uv：解决方案是直接修改环境变量UV_CACHE_DIR到跟项目文件夹一个磁盘上（比如我代码在D盘上，但是默认缓存路径在C盘。用uv cache dir命令就可以检查缓存路径在哪里）。Win11修改方法是直接在系统中搜索“环境变量”，打开这个：
在这里插入图片描述

新建系统变量：
在这里插入图片描述

确定后，重启一遍代码编辑器就好了。

4.2 管理依赖

https://docs.astral.sh/uv/guides/projects/#managing-dependencies

添加依赖包的命令：
uv add requests

# Specify a version constraint
uv add 'requests==2.31.0'

# Add a git dependency
uv add git+https://github.com/psf/requests

从pip的requirements.txt批量添加依赖包：

# Add all dependencies from `requirements.txt`.
uv add -r requirements.txt -c constraints.txt

删除包：uv remove requests

更新包版本：uv lock --upgrade-package requests

查看包依赖关系：uv tree

4.3 uv项目之间共享虚拟环境

Using workspaces | uv

大致思路就是在一个uv管理的Python项目工作路径下再uv init新项目，新项目就能直接用当前项目的虚拟环境。
每个子项目都有自己的pyproject.toml，但是都能用父项目中的包。

总之就比如说你先uv init example，然后你在example项目工作目录下（cd example）再uv init新项目就会视为example的子项目，会添加在tool.uv.workspace的members里：

[tool.uv.workspace]
members = [
    子项目,
]

整个workspace下

以下内容来自官方文档，但我不一定理解正确，仅供参考↓

父项目的pyproject.toml就长类似这样：

[project]
name = "albatross"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = ["bird-feeder", "tqdm>=4,<5"]

[tool.uv.sources]
bird-feeder = { workspace = true }

[tool.uv.workspace]
members = ["packages/*"]
exclude = ["packages/seeds"]

albatross项目就是父项目，packages文件夹里除了seeds项目的所有项目都是子项目。
uv run uv run --package albatross等价

bird-feeder是albatross的父项目
uv run --package bird-feeder就会用项目bird-feeder的虚拟环境来运行

tool.uv.sources标识的是包的来源。子项目默认会继承父项目的，但可以覆写。
示例：

[tool.uv.sources]
bird-feeder = { workspace = true }
tqdm = { git = "https://github.com/tqdm/tqdm" }

bird-feeder = { workspace = true }这个表示默认用bird-feeder的包

5. uv + Jupyter Notebook

https://docs.astral.sh/uv/guides/integration/jupyter/

6. 对一个现成的pip管理的Python项目，用uv无缝衔接pip命令进行管理

就是本来是用pip管理的一个项目文件夹。

uv venv .venv --python=3.10：会在本地创建一个.venv文件夹，创建venv虚拟环境

.venv\Scripts\activate：（Windows系统）进入虚拟环境

uv pip install -r requirements.txt：根据requirements.txt下载依赖

然后单独想要下载什么包，可以用类似pip的语法，如：uv pip install loguru