python包管理神器【uv】详解

原创 已于 2025-08-02 23:07:10 修改 · 5k 阅读 · 48 ·
CC 4.0 BY-SA版权
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
文章标签：

#python #uv #开发语言 #pip #virtualenv

于 2025-05-12 19:43:41 首次发布
本文章已经生成可运行项目，

目录

本文最后一次更新于 2025.8.2

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页下载。

方式二：命令行安装(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、%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 命令帮助

uv
uv hlep
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版本。

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

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

3.2 uv python install安装python

#安装最新版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 [命令]都接受的参数：

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

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文件包含自带标准库以外的库，则需额外添加参数
#以requests（第三方包）为例：
uv run --with requests 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管理项目

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

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 tree 树状图显示项目依赖关系

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 某某.py

前提：存在目录.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）的情况下软件包能够正确地构建。

本文章已经生成可运行项目
若叶.
关注
Python 新一代包管理工具 `uv`：从入门到进阶
强化学习曾小健
02-15 7687
uvuv凭借其极速和一体化设计，正逐步成为 Python 开发者的新选择。无论是小型脚本还是大型项目，它都能显著提升开发效率。未来随着功能迭代（如原生多版本 Python 支持），其生态潜力将更加强大。
新的Python库、项目管理工具——uv
CS创新实验室
01-05 5336
uv 是一个革命性的 Python 工具，旨在简化并加速 Python 项目的依赖管理和开发流程。它结合了高性能、多功能性和易用性，是 Python 开发者值得尝试的新工具。如果你对现有的工具链感到不满，或者希望提升开发效率，uv 是一个绝佳的选择。
【Python】使用uv管理python虚拟环境
慕雪华年的博客
04-26 1万+
本文介绍了python虚拟环境管理工具uv，包括uv的作用、uv的常用命令等等。
【Python】Python 版本、项目、包、管理工具UV
最新发布
zww学习笔记
06-30 306
UV 是由 Astral 团队使用 Rust 编写开发的极快速的 Python 包和项目管理工具。它集成了多种常用 Python 工具（如 pip、pip-tools、poetry、pyenv 等）的功能，提供了一个统一的工具来管理项目依赖、环境、脚本和 Python 版本。
高效Python开发：uv包管理器全面解析
General_zy的博客
05-10 2324
uv 是由 Astral 公司开发的 Rust 编写的快速 Python 包管理器，旨在取代 pip 和其他相关工具，提供端到端的 Python 项目管理解决方案。其主要功能包括包管理、虚拟环境管理、Python 版本控制、CLI 工具管理以及单文件脚本支持。uv 具有高性能，依赖解析和安装速度显著优于传统工具，且支持跨平台操作（macOS、Linux、Windows）。它兼容 pip 接口，同时提供类似 Cargo 的现代化工作流，适合从初学者到专家的各类开发者。安装方式灵活，支持通过独立安装器或 PyP
Python 包管理器 UV 全面介绍
刘炫320的博客
03-27 4915
今天看到一个新的工程，推荐我用UV进行包管理器，作为一个10年老python人员，我居然不知道UV是什么。于是，我就去查了一下UV。
python uv 新一代包管理工具
AdleyTales的技术博客
02-26 5521
uv 高效的包管理工具，替代pip。用rust编写。
python包管理工具——uv
qq_42019881的博客
02-19 8498
uv是一个非常快的Python包和项目管理器，用Rust编写。使用热缓存安装Trio的依赖项的速度对比。
Python包管理不再头疼：uv工具快速上手
fenfenfen520a的博客
12-27 6924
Python 包管理生态中存在多种工具，如 pip、pip-tools、poetry、conda 等，各自具备一定功能。 而今天介绍的uv 是 Astral 公司推出的一款基于 Rust 编写的 Python 包管理工具，旨在成为 “Python 的 Cargo”。 它提供了快速、可靠且易用的包管理
Python 依赖包管理工具：uv
blues_C的博客
02-20 5086
UV 是一个用 Rust 编写的 Python 包安装和依赖管理工具，比传统工具（如 pip）有着更快、更高效的体验。UV 在包安装、依赖解析和虚拟环境创建等方面进行了优化，速度有显著的提升。UV 可以减少资源消耗，尤其是在大型项目中。UV 基于 pip 和 venv 的概念，因此与现有 Python 生态系统兼容，学习曲线相对平缓。UV 是一个新兴的 Python 包安装和依赖管理工具，凭借其用 Rust 编写的高效实现，在速度和资源占用方面显著优于传统的 pip 和 virtualenv。
03 python包管理工具——uv
weixin_54388827的博客
05-04 1010
一个速度极快的 Python 包和项目经理，用 Rust 编写。
Python科学计算包numpy用法实例详解
12-25
本文实例讲述了Python科学计算包numpy用法。分享给大家供大家参考，具体如下： 1 数据结构 numpy使用一种称为ndarray的类似Matlab的矩阵式数据结构管理数据，比python的列表和标准库的array类更为强大，处理数据更为...
Python上下文管理器全实例详解
09-18
在本篇文章里小编给大家整理的是关于Python上下文管理器全实例解析的知识点，需要的朋友们参考下。
Python登录系统界面实现详解
12-31
tkinker在python2.5以后就是自带包了，所以我们不需要另外安装 tkinker相对与其他python GUI编程的包而已，是相对容易入手的 代码篇 这是系统的登录界面  import tkinter from tkinter import messagebox class...
python后端开发spider框架详解
04-28
python、后端、spider、进阶、爬虫
【Python新手入门指南】极速搭建Python开发环境
热门推荐
专注Rust编程与技术分享，涵盖C++、Python等开发实战，新手友好，专注实战，助力编程成长。
06-05 1万+
Python开发环境快速搭建指南：使用新一代工具uv 本文针对Python开发者面临的环境配置问题，介绍了基于uv工具的高效解决方案。文章详细讲解了uv在Windows、Mac和Linux系统的安装方法，以及基本使用流程：项目初始化、依赖管理（uv add）、代码检查（uv run ruff check）、依赖锁定（uv lock）和更新（uv sync）。uv相比传统工具具有显著优势：超快的依赖安装速度、跨平台支持、轻量级虚拟环境管理（10倍于virtualenv）以及内建的脚本管理功能。通过uv，开发者
新一代Python管理UV完全使用指南｜附实际体验与效果对比
深度学习机器
05-29 1471
uv包含以下命令，前几个是比较常用的。命令描述run运行命令或脚本init创建一个新项目add向项目中添加依赖项remove从项目中移除依赖项sync更新项目的环境lock更新项目的锁定文件export将项目的锁定文件导出为其他格式tree显示项目的依赖树tool运行和安装由 Python 包提供的命令python管理 Python 版本和安装pip使用兼容 pip 的接口管理 Python 包venv创建虚拟环境build将 Python 包构建为源代码分发包和 wheelspublish。
Python 项目管理神器 uv 深度解析：从初始化到发布的全流程指南
佑瞻的博客
04-26 4604
uv 支持生成标准的 Python 发行包（源包和 wheel 包），只需：bashuv build # 在当前目录构建项目ls dist/ # 查看生成的发行包（.tar.gz和.whl文件）构建时支持指定源目录或工作区中的子包：bashuv build src/my_package # 构建指定目录的包uv build --package my_lib # 构建工作区中的指定包。
uv、python打包工具
03-25
### Python 打包工具 UV 的使用方法 UV 是一种高效的 Python 包管理工具，旨在简化开发者的工作流程并提供一致的环境配置体验[^1]。以下是关于如何使用 UV 进行 Python 开发的相关说明。 #### 安装 UV 要安装 UV，可以通过官方文档或其他可信渠道获取安装脚本。通常情况下，可以直接运行以下命令完成安装： ```bash curl https://get.uv.sh | bash ``` 此命令会自动检测操作系统，并下载适合的二进制文件进行安装。 #### 配置 Python 环境 一旦 UV 被成功安装，即可利用其内置功能来管理和切换不同的 Python 版本。例如，如果需要安装特定版本的 Python，则可以执行以下命令： ```bash uv python install 3.9 ``` 上述命令会让 UV 自动从官方网站下载指定版本的 Python 并将其添加至系统的 PATH 中。 #### 创建项目结构与依赖管理 对于新项目的初始化，推荐创建 `pyproject.toml` 文件用于定义构建系统和其他元数据信息。假设当前目录下已经存在一个名为 `setup.py` 或者其他形式的描述符文件，那么可通过以下方式生成锁文件（lock file），从而固定所有依赖项的具体版本号： ```bash uv lock generate --output=uv.lock ``` 这一步骤类似于传统 Pipenv 流程中的 `Pipfile.lock` 生产过程，不过最终产物被命名为 `uv.lock` 来区分不同工具链之间的差异[^4]。 #### 构建分发档案 当准备分享自己的库或者应用程序给其他人时，就需要借助于 sdist (source distribution) 和 wheel (binary distribution) 形式的压缩包。这些操作同样能够由 UV 提供的支持轻松实现： ```bash uv build . ``` 该指令会在本地路径上查找必要的元数据源码位置，并按照 PEP 517/PEP 518 标准规范打包成果物[^2]。 --- ### 注意事项 尽管 UV 功能强大且易于学习掌握，但在实际应用过程中仍需注意一些细节问题： - **多版本共存处理**：由于许多用户的机器可能同时拥有多个解释器实例，在调用相关 CLI 命令前务必确认目标对象无误； - **跨平台兼容性验证**：考虑到 Windows/Linux/macOS 存在细微差别之处，建议尽可能多地测试各种场景下的行为表现一致性； ---
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值