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

一、基础概念

• 什么是 Python 脚本
  
  
  
  • 以 .py 结尾的文件，可通过 python script.py 独立执行。
    
  • UV 工具上风：无需手动创建或激活捏造环境，自动为每个脚本生成隔离环境，包管依靠互不干扰。
    
  
  
• 环境管理原理
  
  1. graph LR
  2.   A[系统 Python 环境] --> B[虚拟环境隔离]
  3.   B --> C[UV 自动创建临时环境]

  复制代码
  
  
  • 当执行 uv run 时，UV 会自动在背景生成一个临时捏造环境，仅安装当前脚本所需的依靠，脚本执行完毕后可复用或销毁该环境。
    
  
  

   提示：假如不熟悉捏造环境，可参考 Python 自带的 venv 模块。uv 会在背景帮你管理环境，并且保举“声明式”地在脚本里写明依靠。
  学习建议：
   

• 从无依靠脚本起步，熟悉 uv run 基本用法；
  
• 再实验临时依靠模式，明白 --with；
  
• 最终过渡到内联依靠，编写更稳定、可复现的脚本。
  遇到问题时，uv run --verbose 脚本.py 可检察详细执行日志，帮助排查。
  

  

---

二、基础使用

1. 无依靠脚本

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

复制代码

无额外依靠时，直接运行即可。
2. 带命令行参数

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

复制代码

命令行参数会按顺序传入脚本，sys.argv[1:] 即所有参数列表。
3. 从标准输入读取

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

复制代码

或使用 here-doc：

1. $ uv run - <<EOF
2. print("多行脚本测试")
3. EOF
4. 多行脚本测试

复制代码

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

1. uv run --no-project hello.py

复制代码

---

三、依靠管理

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

得当偶然必要外部库，但不想在脚本里永世添加依靠的场景。

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

复制代码

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

2. 永世依靠（内联声明）

保举做法，在脚本顶部声明依靠，UV 会自动识别并安装。

1. # /// script
2. # dependencies = ["requests", "rich"]
3. # ///
5. import requests
6. from rich import print
8. resp = requests.get("https://api.example.com")
9. print(resp.status_code, resp.text)

复制代码

管理命令：

1. $ 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，可直接双击或命令行执行，无需写命令。
  
  1. #!/usr/bin/env -S uv run --script
  2. print("脚本可执行！")

  复制代码
  授予执行权限：
  
  1. chmod +x script
  2. ./script

  复制代码
• 跨平台 GUI 开发
  
  
  
  • Windows 下使用 .pyw 扩展，UV 会用 pythonw 运行，无控制台窗口。
    
  • 同样支持依靠管理：
    
  1. # app.pyw
  2. from tkinter import Tk, Label
  3. root = Tk()
  4. Label(root, text="UV GUI 示例").pack()
  5. root.mainloop()

  复制代码
  1. uv run --with PyQt5 app.pyw

  复制代码
  
  

---

六、常见问题

Q1：为何出现 ModuleNotFoundError？
A：分析脚本缺少依靠声明，可用

1. uv add --script 脚本.py 包名

复制代码

或在执行时临时加 --with 包名。
Q2：如何包管他人环境也能正常运行？
A：使用锁定命令：

1. uv lock --script 脚本.py

复制代码

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