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

一、基础概念

1. 什么是 Python 脚本

   • 以 .py 结尾的文件，可通过 python script.py 独立执行。
   • UV 工具优势：无需手动创建或激活虚拟环境，自动为每个脚本生成隔离环境，保证依赖互不干扰。

2. 环境管理原理

   graph LRA[系统 Python 环境] --> B[虚拟环境隔离]B --> C[UV 自动创建临时环境]
   

   • 当执行 uv run 时，UV 会自动在后台生成一个临时虚拟环境，仅安装当前脚本所需的依赖，脚本执行完毕后可复用或销毁该环境。

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

学习建议：

1. 从无依赖脚本起步，熟悉 uv run 基本用法；
2. 再尝试临时依赖模式，理解 --with；
3. 最终过渡到内联依赖，编写更稳定、可复现的脚本。
   遇到问题时，uv run --verbose 脚本.py 可查看详细执行日志，帮助排查。

---

二、基础使用

1. 无依赖脚本

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

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

2. 带命令行参数

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

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

3. 从标准输入读取

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

或使用 here-doc：

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

项目模式
如果当前目录包含 pyproject.toml，uv run 会默认安装项目依赖。
如只想运行脚本并忽略项目本身，需在命令前加 --no-project：

uv run --no-project hello.py

---

三、依赖管理

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

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

# 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 会自动识别并安装。

# /// script
# dependencies = ["requests", "rich"]
# ///import requests
from rich import printresp = requests.get("https://api.example.com")
print(resp.status_code, resp.text)

管理命令：

$ 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 配置和环境问题，给出修复建议

---

五、最佳实践

1. 创建可执行脚本（类 Unix 系统）
   在脚本顶部添加 shebang，可直接双击或命令行执行，无需写命令。

   #!/usr/bin/env -S uv run --script
   print("脚本可执行！")
   

   授予执行权限：

   chmod +x script
   ./script
   

2. 跨平台 GUI 开发

   • Windows 下使用 .pyw 扩展，UV 会用 pythonw 运行，无控制台窗口。
   • 同样支持依赖管理：

   # app.pyw
   from tkinter import Tk, Label
   root = Tk()
   Label(root, text="UV GUI 示例").pack()
   root.mainloop()
   

   uv run --with PyQt5 app.pyw
   

---

六、常见问题

Q1：为何出现 ModuleNotFoundError？
A：说明脚本缺少依赖声明，可用

uv add --script 脚本.py 包名

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

Q2：如何保证他人环境也能正常运行？
A：使用锁定命令：

uv lock --script 脚本.py

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