Python 包管理工具 UV

前言——碎碎念

UV 是一个第三方 Python 包管理工具，可以替代官方的 pip。

其优点是速度快、可以切换多个版本的 python、管理第三方包的虚拟环境等。更多内容可以看官方文档

个人认为用起来比Conda舒服得多，速度真的快了很多

要我说，uv知名度还是太低了，Ai都不认识uv，搜索引擎也不认识，不如在前面加个a : )

安装

Windows：powershell -ExecutionPolicy Bypass -c "irm https://github.com/astral-sh/uv/releases/download/0.9.27/uv-installer.ps1 | iex"

Linux/Mac OS：

curl -LsSf https://astral.sh/uv/install.sh | sh

uv 的运行程序安装在C:\Users\[Your Name]\.local\bin，要将其添加到环境变量 path，一般来说安装时会自动添加

Python 管理

查看 uv 支持的 Python 版本：

uv python list

会列出当前电脑安装的 Python 版本以及可以安装的 Python 版本：

可以使用以下命令安装特定版本的 Python：

uv python install 3.13.6

如果不指定版本号，将安装最新版本的 Python

使用uv安装的python会被安装到.local\bin目录

可以使用uv run来命令运行指定版本的 python：

> uv run -p 3.13 python
Python 3.13.6 (main, Aug  8 2025, 17:02:53) [MSC v.1944 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.

直接命令行运行也行

❯ python3.13
Python 3.13.6 (main, Aug  8 2025, 17:02:53) [MSC v.1944 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.

Python脚本运行

给出一个简单的脚本，功能就是输出hello world

print(hello world)  //hello.py

用uv run命令运行是完全可行的

>uv run -p .\hello.py
hello world

这个脚本没有引用任何第三方库，自然可以正常运行

现在这个脚本升级了，变成了这样

from flask import Flask

app = Flask(__name__)

@app.route('/')
def hello_world():
    return 'Hello'
if __name__ == '__main__':
    app.run(debug = True)

这是一个用flask写的hello world，即引用了第三方库flask

直接运行肯定会报错：

> uv run .\flask.py
cannot import name 'Flask' from partially initialized module 'flask' (most likely due to a circular import) (D:\code\code\python\flask.py)
  File "D:\code\code\python\flask.py", line 1, in <module>
    from flask import Flask
  File "D:\code\code\python\flask.py", line 1, in <module>
    from flask import Flask
ImportError: cannot import name 'Flask' from partially initialized module 'flask' (most likely due to a circular import) (D:\code\code\python\flask.py)

因为环境缺少第三方库，需要安装库后才能正常运行

可以在执行 run 命令时通过参数指定脚本运行需要的第三方库，这样如果环境缺少第三方库就会安装后再执行脚本：

❯ uv run --with 'flask' .\flask.py
For example: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:01

还可以可以指定版本

❯ uv run --with 'rich>12,<13' .\test.py
For example: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:01

这是一种一次性临时安装方式，不会出现依赖冲突的现象

也就是说这种方式只适用于单独的脚本文件，不要对 Python 项目中的 Python 文件使用

Python依赖管理

要管理项目依赖，首先就得有个项目

可以通过 uv 创建项目目录：

uv init hello-world

如果项目目录已经存在，可以使用uv init命令初始化当前目录为项目目录

创建完成后，会出现项目目录

使用 cd .\hello-world\来指定该环境，输入 ls 查看项目目录

>cd .\hello-world\
>ls

      目录: D:\code\code\hello-world

Mode          LastWriteTime             Length Name
----         -------------             ------ ----
-a----        2026/1/27 23:38 5       .python-version
-a----        2026/1/27 23:38 89       main.py
-a----        2026/1/27 23:38 157      pyproject.toml
-a----        2026/1/27 23:38 0        README.md

.python-version这个文件记录了当前项目运行的 python 版本，这样 uv 在运行时就会以指定版本运行项目，要换版本直接修改就行

有了项目框架，项目中的依赖同样可以使用 uv 进行管理

>uv add flask
>uv add [第三方库]

uv 会自动在项目目录下创建一个.venv目录作为虚拟环境的依赖包的安装目录，并且在项目描述文件pyproject.toml中添加依赖信息

然后把需要运行的脚本放到hello-wrold这个环境中，直接uv run运行即可，这里用上文的flask.py举例

>uv run flask.py
 * Serving Flask app 'hello'
 * Debug mode: on
 * Running on http://127.0.0.1:5000

现在你的项目就可以运行了

如果想查看自己安装的库：

>uv pip list

如果你还想知道所有库之间的依赖关系：

>uv tree

输入后会打印出整个依赖树

现在这个第三方库我不想用了，怎么移除依赖：

>uv remove flask
>uv remove [第三方库]

安装项目/工具

在开发过程中，我们会使用很多的工具

如上文使用的Flask网站框架，或是代码检查工具ruff，本文学习的uv也是一种包管理和环境管理工具

要想使用工具，我们可以直接把工具像依赖一样安装

添加ruff工具:

>uv add ruff --dev

输入后就能直接使用工具了

>uv run ruff check
All checks passed!

–dev的作用是防止打包的时候把ruff一起打包进来，只在开发中使用，打包下文会讲

因为ruff是一种工具，不推荐直接依赖安装，–dev里应该装和代码有关的，这是笔者的个人习惯，直接放–dev里也没错

第二种方法就是用uv tool，可以安装、更新项目，其用途类似于 pip

比如安装已发布的项目：

>uv tool install ruff
>uv tool install [已发布项目]

更新已安装的项目：

>uv tool upgrade ruff    //更新ruff
>uv tool upgrade --all   //更新所有通过 uv 安装的项目

查看已经安装的项目:

>uv tool list
ruff v0.14.14
- ruff

用uv tool install安装的项目在当前用户下是全局可用的，并不会局限于某个环境

uv会自动为每个项目都创建虚拟环境，换言之通过这种方式安装的包之间是互相隔离的，不需要担心库之间的冲突

因为工具不依赖于任何特定的 Python 环境，所以说也就不能直接import ruff导入，想要导入就用pip install或者uv add安装

uv还有个很好用的特色命令uvx：

# 临时运行某个工具，无需事先安装
uvx ruff --help

# 指定版本
uvx ruff@0.1.0 --help

# 运行任意脚本
uvx --from https://example.com/script.py

# 运行 GitHub 上的脚本
uvx --from github:astral-sh/ruff

Python项目打包

使用 uv build命令可以创建（打包） python 项目的二进制发行版本（.whl文件）：

❯ uv build

生成的文件保存在dist目录下

然后就可以uv add或者uv tool install安装了

Python项目打包——拓展

在打包之前，可以打开pyproject.toml这个文件，添加：

[project.scripts]
hello = "hello2:main" 
//[命令名] = "[包名]:[函数名]"

在Python中，”包名”指的是Python包的名称。一个Python包是一个包含__init__.py文件的目录，该目录下可以有多个模块（.py文件）和子包

当你在命令行中输入命令名（hello）时

• 1.找到hello2这个 Python 包
• 2.找到其中的 main 模块
• 3.调用其中的 main() 函数

例如main函数里就一个print（'hello-world'）

>hello
hello-world

本文章采用 CC BY 4.0 协议进行许可