python包管理神器【uv】详解

1 uv简介与安装

1.1 uv作用

作用：管理python版本、管理项目、管理包等作用。

原话： A single tool to replace pip, pip-tools, pipx, poetry, pyenv, twine, virtualenv, and more.

特点：快。
官网文档：https://docs.astral.sh/uv/

1.2 安装

方式一：github/release页下载。

• https://github.com/astral-sh/uv/releases选择符合系统的版本下载并解压。
• 添加下载路径到环境变量（win+q后输入环境变量，环境变量）
• 手动添加配置文件：%localappdata%/uv/uv-receipt.json

{"binaries":["uv.exe","uvx.exe"],
"binary_aliases":{},
"cdylibs":[],
"cstaticlibs":[],
"install_layout":"flat",
"install_prefix":"这里改为你自己解压的路径，例如：D:\\Python\\uv",
"modify_path":true,
"provider":{"source":"cargo-dist","version":"0.28.4"},
"source":{"app_name":"uv","name":"uv","owner":"astral-sh","release_type":"github"},
"version":"0.7.3"}

其中install_prefix内容改为自己安装路径

• 该方式后续更新，终端运行：

 uv self update

方式二：命令行安装(win)

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

该方式后续更新，终端运行：

uv self update

方式三：pypi安装

• pipx install uv或pip install uv。建议用pipx
• 更新：pip install --upgrade uv

确认安装成功

输入uv self version，显示版本信息即完成。

1.3 卸载

• 清缓存uv cache clean
• 删除%localappdata%/uv和%appdata%uv
• 删除uv.exe存储路径

2 命令帮助

uv
uv hlep
uv 命令 --help
uv help 命令

均可，遇到不会的命令可随时使用以上来查看提示信息。

3 uv管理python版本

通过uv安装的python无法全局使用，仅可通过uv使用。
python [命令]×
uvx python -c [命令]√

3.1 uv python --参数

# 仅显示uv管理的python版本，不显示系统安装的python版本。
uv python [命令] --managed-python
# 和上一个相反。仅显示系统安装版本。
uv python [命令] --no-managed-python

3.2 uv python list

列出当前的python版本。

# 列出当前【已安装】的python版本
uv python list --only-installed	

# 列出【可安装】的python版本
uv python list --only-downloads

3.3 uv python install

安装最新版python，如果已安装有python(无论是否最新)，则不运行。

# 安装3.13版本python(默认CPython)
uv python install 3.13

# 安装3.10版本pypy
uv python install pypy 3.10

• 默认安装&管理路径%appdata%/uv/python，可通过命令uv python dir查看。可以通过环境变量UV_PYTHON_INSTALL_DIR修改为指定路径。
• 卸载就是把install换成uninstall。略。

4 uv运行单个脚本

4.1 uv run .py文件

以指定版本python运行.py文件

# 以默认python运行start.py
uv run start.py

# 以指定版本python运行.py文件
uv run -p 3.12 start.py

#如果py文件包含自带标准库以外的库，则需额外添加参数
#以flask（第三方包）为例：
uv run --with flask app.py

uv会先下载flask库，然后运行app.py。库会下载到uv cache dir位置，默认为%localappdata%/uv/cache

4.2 uv init --script

创建example.py脚本

# 创建以py3.12运行的脚本example.py
uv init --script example.py --python 3.12

# 如果脚本中需要引入第三方库'requests' 和 'rich'：
uv add --script example.py 'requests<3' 'rich'

example.py开头会自动包含以下：

4.3 uv lock --script

锁定依赖

# 锁定脚本example.py的依赖
uv lock --script example.py

运行后，会创建同名.lock文件。锁定之后，如果再次运行uv add --script``uv remove --script等命令，.lock文件可能会同样跟新。

5 uv管理项目

5.1 初始化项目

# 创建名为`auto`的文件夹并初始化
uv init auto

# 初始化当前目录
uv init

uv init audo = 创建auto文件夹 + 进入auto文件夹 + 在auto内运行uv init
初始化后包含文件：

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

5.2 添加虚拟环境

在项目内，运行uv run、uv lock、uv sync等命令时，会创建uv.lock、.venv文件

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

pycharm新建项目时选择uv，自动创建.venv和pyproject.toml

5.3 项目文件

pyproject.toml

官方文档：https://packaging.python.org/en/latest/guides/writing-pyproject-toml/
包含项目相关配置数据。

.python-version

.python-version文件包含项目的默认Python版本。该文件告诉uv在创建项目虚拟环境时使用哪个Python版本。

.venv

虚拟环境，项目安装依赖所在目录

uv.lock

uv.lock是一个跨平台的锁定文件，它包含关于您项目依赖关系的精确信息。与用于指定项目广泛需求的pyproject.toml不同，锁定文件包含在项目环境中安装的确切解析版本。此文件应提交到版本控制中，以便在不同机器上实现一致且可重现的安装。由uv管理，不应手动编辑。
该文件仅由uv使用，其他工具无法使用。

pylock.toml
在PEP 751(点击跳转)中，Python标准化了一种新的解析文件格式，即pylock.toml。
pylock.toml是一种旨在替代requirements.txt（例如，在uv pip compile的上下文中，从一组输入要求生成一个锁定的requirements.txt文件）的解析输出格式。pylock.toml是标准化的且与工具无关，因此在未来，由uv生成的pylock.toml文件可以被其他工具安装，反之亦然。
uv的一些功能无法以pylock.toml格式表达；因此，uv将继续在项目接口内使用uv.lock格式。
然而，uv支持将pylock.toml作为导出目标以及在uv pip CLI中使用。例如：
要将uv.lock导出为pylock.toml格式，运行：uv export -o pylock.toml
要从一组要求生成pylock.toml文件，运行：uv pip compile -o pylock.toml -r requirements.in
要从pylock.toml文件安装，运行：uv pip sync pylock.toml或uv pip install -r pylock.toml

5.4 安装依赖

uv add

uv add 库名

# 使用指定版本的库
uv add 'requests==2.31.0'

# 从git仓库导入库
uv add git+https://github.com/psf/requests

# 指定链接导入。支持后缀：'.tar.gz' 、 '.whl' 、 '.zip'等
uv add "https://files.pythonhosted.org/packages/5c/2d/3da5bdf4408b8b2800061c339f240c1802f2e82d55e50bd39c5a881f47f0/httpx-0.27.0.tar.gz"

# 本地其他路径导入库。支持后缀同上。绝对路径和相对路径均可。
uv add /myPagePath/good-0.1.0.whl

# 以requirments.txt文件批量下载
uv add -r requirments.txt

作用：下载依赖项、同时更新uv.lock、pyproject.toml。
强烈不建议使用uv pip install！！！
uv add=uv pip install + 编辑pyproject.toml + 编辑uv.lock

uv pip list

列举已安装的包

uv remove

作用：删除依赖项、同时更新uv.lock、pyproject.toml。

uv lock --upgrade

# 更新指定包到兼容的最新版本，同时不影响其他包
uv lock --upgrade-package requests

# 更新多个包
uv lock --upgrade-package 包1 --upgrade-package 包2

# 更新全部
uv lock --upgrade

尝试将指定的包更新到最新兼容版本，同时保留锁定文件的其余部分不变。

uv sync

根据当前项目的依赖配置（如 pyproject.toml 和 uv.lock 文件）同步更新虚拟环境.venv

激活虚拟环境

要在项目中运行脚本和命令而不使用uv run，必须激活虚拟环境。虚拟环境的激活因shell和平台而异。

• bash:

source .venv\Scripts\activate
flask run -p 3000
python example.py

• powershell:

./.venv/scripts/activate.ps1
flask run -p 3000
python example.py

• cmd

.venv\Scripts\activate.bat
flask run -p 3000
python example.py

5.5 利用虚拟环境中python运行脚本

uv run python

前提：存在目录.venv

# 运行指定命令
uv run python -c 'import sys;print(sys.executable)'
# 输出：D:\Python\Project\auto\.venv\Scripts\python.exe。
# ！可见确实用的虚拟环境中的解释器


# 运行指定脚本
uv run python main.py


# 如果临时运行一个脚本，脚本中有还包含【未安装的包】
uv run --with httpx==0.26.0 python -c "import httpx,sys; print(httpx.__version__);print(sys.executable)"
# 输出：0.26.0
# 输出：C:\Users\myuer\AppData\Local\uv\cache\archive-v0\AvKaefqT2QIDzAksSYIBH\Scripts\python.exe
# ！--with参数会临时创建一个【额外】的隔离环境。不在.venv中

uv.lock 锁文件

运行uv run时，uv会自动更新uv.lock文件并更新环境(即自动运行uv lock+uv sync)
如果uv.lock文件不是最新的(即pyproject.toml中手动添加了一个依赖，但uv.lock未添加)，则会返回错误，而不是自动更新uv.lock

uv lock --check

检查锁文件是否最新(是否与pyproject.toml同步)

uv lock

更新锁文件uv.lock。

uv sync

虚拟环境会自动更新。也可以手动运行命令uv sync来更新环境。
锁文件是非常精确地：如果环境中存在uv.lock文件中列表以外的包，将会被删除。如果要保留多余的软件包，添加参数--inexact

# 更新环境，但保留已存在的多余的包(不在uv.lock描述中的包)
uv sync --inexact

导出依赖为通用格式

# 将uv.lock导出为requirements.txt格式，并保存到re.txt文件
uv export --format requirements.txt -o re.txt
# 如果存在-o保存到文件选项，可简写
uv export -o re.txt


# 将uv.lock导出为pylock.toml格式，并保存到pylock.toml文件
uv export --format pylock.toml -o pylock.toml
# 如果存在-o保存到文件选项，可简写
uv export -o pylock.toml

官方文档引用(点击跳转)：生成的requirements.txt文件可以通过uv pip install安装，也可以使用其他工具如pip来安装。
一般来说，我们不建议同时使用uv.lock和requirements.txt文件。如果您发现自己正在导出uv.lock文件，请考虑开一个issue来讨论您的用例。

6 构建

uv build

uv构建可用于为您的项目构建源分发和二进制分发（wheel）。
默认情况下，uv构建将在当前目录中构建项目，并将构建的工件放置在dist/子目录中。
略。

在发布软件包时，我们建议运行 uv build --no-sources 以确保在禁用 tool.uv.sources（例如使用其他构建工具，如 pypa/build）的情况下软件包能够正确地构建。