【Python】UV：单脚本依赖管理

一、基础概念

什么是 Python 脚本
- 以 .py 结尾的文件，可通过 python script.py 独立执行。
- UV 工具优势：无需手动创建或激活虚拟环境，自动为每个脚本生成隔离环境，保证依赖互不干扰。
环境管理原理
复制代码
```
graph LR
  A[系统 Python 环境] --> B[虚拟环境隔离]
  B --> C[UV 自动创建临时环境]
```
- 当执行 uv run 时，UV 会自动在后台生成一个临时虚拟环境，仅安装当前脚本所需的依赖，脚本执行完毕后可复用或销毁该环境。

提示：如果不熟悉虚拟环境，可参考 Python 自带的 venv 模块。uv 会在后台帮你管理环境，并且推荐"声明式"地在脚本里写明依赖。

学习建议：

从无依赖脚本起步，熟悉 uv run 基本用法；

再尝试临时依赖模式，理解 --with；

最终过渡到内联依赖，编写更稳定、可复现的脚本。
遇到问题时，uv run --verbose 脚本.py 可查看详细执行日志，帮助排查。

二、基础使用

1. 无依赖脚本

python 复制代码

# hello.py
print("你好，世界！")
$ uv run hello.py
你好，世界！

无额外依赖时，直接运行即可。

2. 带命令行参数

python 复制代码

# greet.py
import sys
print(" ".join(sys.argv[1:]))
$ uv run greet.py 你好 Python
你好 Python

命令行参数会按顺序传入脚本，sys.argv[1:] 即所有参数列表。

3. 从标准输入读取

bash 复制代码

$ echo 'print("stdin 运行!")' | uv run -
stdin 运行!

或使用 here-doc：

bash 复制代码

$ uv run - <<EOF
print("多行脚本测试")
EOF
多行脚本测试

项目模式

如果当前目录包含 pyproject.toml，uv run 会默认安装项目依赖。

如只想运行脚本并忽略项目本身，需在命令前加 --no-project：
bash 复制代码
uv run --no-project hello.py

三、依赖管理

1. 临时依赖（单次运行）

适合偶尔需要外部库，但不想在脚本里永久添加依赖的场景。

python 复制代码

# progress.py
from rich.progress import track
for _ in track(range(10), description="加载中"):
    pass
$ uv run --with rich progress.py
加载中 ━━━━━━━━━━━━━━ 100% 0:00:00

--with rich：当前执行临时安装并使用 rich 库。
可多次使用 --with 添加多个包。

2. 永久依赖（内联声明）

推荐做法，在脚本顶部声明依赖，UV 会自动识别并安装。

python 复制代码

# /// script
# dependencies = ["requests", "rich"]
# ///

import requests
from rich import print

resp = requests.get("https://api.example.com")
print(resp.status_code, resp.text)

管理命令：

bash 复制代码

$ uv add --script demo.py requests rich

该命令会在脚本头部生成或更新 dependencies 列表。
后续直接 uv run demo.py 即可，无需再加 --with。

注意：使用内联依赖时，若在项目目录下运行，也不会安装项目依赖，脚本只关心自己声明的包。

四、相关管理命令

功能场景	命令示例	说明
指定 Python 版本	`uv run --python 3.10 demo.py`	若本地无该版本，UV 会自动下载并使用
锁定依赖版本	`uv lock --script demo.py`	生成 `demo.py.lock`，用于可重复运行
导出依赖清单	`uv export --script demo.py`	输出 `requirements.txt` 或等效格式，方便分享
查看依赖树	`uv tree --script demo.py`	以树状结构展示当前脚本依赖及其互相引用
移除脚本依赖	`uv remove --script demo.py package_name`	从内联声明中删除指定包
清理环境	`uv clean demo.py`	删除该脚本对应的虚拟环境，以便重新创建
使用私有源	`uv add --index https://私有源/simple --script demo.py 包名`	将私有索引写入脚本元数据，支持认证
导出锁文件	`uv export --lock demo.py.lock`	将锁文件内容导出为可阅读格式
查看脚本信息	`uv info --script demo.py`	显示已声明依赖、Python 版本需求、索引源等元数据信息
项目依赖安装（全局）	`uv install`	在项目目录安装 `pyproject.toml` 中定义的所有依赖
版本升级	`uv upgrade [package]`	升级指定包或全部包到最新版本
环境诊断	`uv doctor`	检查 UV 配置和环境问题，给出修复建议

五、最佳实践

创建可执行脚本（类 Unix 系统）

在脚本顶部添加 shebang，可直接双击或命令行执行，无需写命令。
bash 复制代码
```
#!/usr/bin/env -S uv run --script
print("脚本可执行！")
```
授予执行权限：
bash 复制代码
```
chmod +x script
./script
```
跨平台 GUI 开发
- Windows 下使用 .pyw 扩展，UV 会用 pythonw 运行，无控制台窗口。
- 同样支持依赖管理：
python 复制代码
```
# app.pyw
from tkinter import Tk, Label
root = Tk()
Label(root, text="UV GUI 示例").pack()
root.mainloop()
```
bash 复制代码
```
uv run --with PyQt5 app.pyw
```

六、常见问题

Q1：为何出现 ModuleNotFoundError？

A：说明脚本缺少依赖声明，可用

bash 复制代码

uv add --script 脚本.py 包名

或在执行时临时加 --with 包名。

Q2：如何保证他人环境也能正常运行？

A：使用锁定命令：

bash 复制代码

uv lock --script 脚本.py

生成 .lock 文件后，可与他人一同分享，确保安装相同版本的依赖。