1 uv简介与安装

1.1 uv作用

由Rust编写。作用：管理python版本、管理项目、管理包等作用。

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

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

！！注：uv工具.zip包含: uv.exe, uvx.exe, uvw.exe

1.2 安装

方式一：github/release页下载。

  • https://github.com/astral-sh/uv/releases选择符合系统的版本下载并解压。
  • 添加下载路径到环境变量（win+q后输入环境变量，环境变量）在这里插入图片描述
    该方式后续更新，下载新版本，解压覆盖。

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

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

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

1
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、%userprofile%/.local

1.4 相关环境变量

#1.2安装中仅设置了uv的环境变量。
而通过uv安装的工具/python时，可能会生成一个.exe文件供uv使用。为了让uv能找到他自己下载工具时生成的.exe文件，需要将%userprofile%/.local/bin加入环境变量。

！可选(推荐):

  • 设置环境变量UV_PYTHON_INSTALL_BIN=false：用uv安装python时不生成额外的python.exe。
  • 不使用uv tool install安装工具，而是用uvx 工具 工具参数，这会将工具安装到缓存位置，默认为%localappdata%/uv/cache。可通过UV_CACHE_DIR修改位置。
    • (uvx为uv tool run别名)
  • 遵循以上两点，可以不设置%userprofile%/.local/bin环境变量

2 命令帮助

1
2
3
4
uv
uv help
uv 命令 --help
uv help 命令

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

3 uv管理python版本

！！注：

  • 默认安装&管理路径%appdata%/uv/python
  • 可通过环境变量UV_PYTHON_INSTALL_DIR修改python安装的位置
  • 可通过命令uv python dir查看python安装目录。输出结果等于以上变量UV_PYTHON_INSTALL_DIR

3.1 uv python list列出版本

列出当前的python版本。

1
2
3
4
5
# 列出当前【已安装】的python版本
uv python list --only-installed

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

3.2 uv python install安装python

1
2
3
4
5
6
7
8
9
10
11
12
#安装最新版python，如果已安装有python(无论是否最新)，则不运行。
uv python install

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

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

# 同时安装多个版本python, 用空格分隔
uv python install 3.11 pypy@3.10 cpython@3.7
# 会同时安装cpython3.11 pypy3.10 cpython3.7三个版本。

卸载就是把install换成uninstall，略。

3.3 全局参数:uv python --参数

所有uv python [命令]都接受的参数：

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

4 uv运行单个脚本

4.1 uv run .py文件

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

1
2
3
4
5
6
7
8
9
# 以默认python运行start.py
uv run start.py

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

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

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

4.2 uv init --script

创建example.py脚本

1
2
3
4
5
# 创建以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

锁定依赖

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

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

5 uv管理项目

通过pycharm可简化5.1, 5.2两步在这里插入图片描述

5.1 初始化项目

1
2
3
4
5
# 创建名为`auto`的文件夹并初始化
uv init auto

# 初始化当前目录
uv init

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

1
2
3
4
5
·
├── .python-version
├── README.md
├── main.py
└── pyproject.toml

5.2 添加虚拟环境

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

1
2
3
4
5
6
7
8
9
10
.
├── .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 安装包

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
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 tree 树状图显示项目依赖关系

uv remove

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

uv lock --upgrade更新包

1
2
3
4
5
6
7
8
# 更新指定包到兼容的最新版本，同时不影响其他包
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:
1
2
source .venv\Scripts\activate
flask --app main run -p 3000
  • powershell:
1
2
./.venv/scripts/activate.ps1
flask --app main run -p 3000
  • cmd
1
2
.venv\Scripts\activate.bat
flask --app main run -p 3000

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

uv run python 某某.py

前提：存在目录.venv

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 运行指定命令
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

1
uv lock --check

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

1
uv lock

更新锁文件uv.lock。

uv sync

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

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

导出依赖为通用格式

1
2
3
4
5
6
7
8
9
10
# 将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 构建

1
uv build

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

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