发个 Python 脚本还要附环境说明?把依赖写进文件头部,uv 一行命令直接跑

你有没有经历过这种尴尬:写了个三十行的小脚本发给同学——抓个网页、批量改文件名、整理下载目录。对方满怀期待地敲下 python xxx.py,回车,满屏飘红:ModuleNotFoundError: No module named 'requests'。
接下来是漫长的远程排障:pip 装了半天、版本对不上、Python 太老要升级……最后你发过去三样东西:脚本本体、requirements.txt、外加一段「记得先装 Python 3.10 以上」的聊天记录。脚本三十行,附件比正文还多。
这个问题其实早就有了标准答案:2024 年 1 月定稿的 PEP 723——把依赖声明写进脚本文件头部的一块注释里;再配上 uv 这个 Rust 写的包管理器,单文件脚本终于可以「自产自销」:拿到文件的人一行命令直接跑,环境、依赖、Python 版本全部自动搞定。
一、uv:先把主角请上台
uv 是 Astral 公司的作品——对,就是做代码格式化工具 ruff 的那家。Rust 编写的 Python 包和项目管理器,目前在 GitHub 上攒了 9.1 万多个 star,最近 B站、掘金上的 Python 教程里它的出镜率也越来越高,基本是新项目环境管理的默认选项了。
安装任选其一:
# macOS / Linux(官方脚本)
curl -LsSf https://astral.sh/uv/install.sh | sh
# 或者用包管理器
pip install uv # Windows 可用 winget install --id=astral-sh.uv -e
brew install uv # macOS Homebrew装完在终端敲 uv --version,能出版本号就绪(写作时最新是 0.13.x)。
二、uv run:先解决「有没有环境」
最朴素的用法:一个只依赖标准库的脚本,直接跑——
# hello.py
import sys
print(" ".join(sys.argv[1:]))uv run hello.py 你好世界注意这里没有先 python -m venv,也没有激活任何环境。uv 会自己找到可用的 Python 解释器(本机没有合适的版本时甚至会自动下载一个),在后台把环境准备好再执行脚本。写小工具的时候,心智负担直接少一半。
如果是临时借一个依赖、不想写进文件,也可以 uv run --with rich demo.py,用完即走,不污染任何环境。
三、PEP 723:把 requirements.txt 折叠进注释
重头戏来了。PEP 723 的全名叫 Inline Script Metadata(内联脚本元数据),思路很直接:单文件脚本犯不着配一个 pyproject.toml,把元数据写进文件头部一块特殊格式的注释就行。
看一个完整的例子,保存为 peps.py:
# /// script
# requires-python = ">=3.10"
# dependencies = [
# "requests<3",
# "rich",
# ]
# ///
import requests
from rich.progress import track
from rich.console import Console
console = Console()
resp = requests.get("https://peps.python.org/api/peps.json", timeout=10)
data = resp.json()
for k, v in track(list(data.items())[:20], description="读取 PEP 清单"):
console.print(f"[bold green]{k}[/] {v['title']}")然后一行命令:
uv run peps.py第一次运行时,uv 会读取头部注释,创建一个隔离环境,装好 requests 和 rich,再执行脚本——带进度条的那种输出效果直接就有了。第二次运行命中缓存,几乎是秒起。
把这个文件原样发给别人,对方唯一的前提是装过 uv,然后同样一行 uv run peps.py。没有 venv,没有 pip install,没有版本诅咒。
几个语法细节值得留意:
# /// script开始、# ///结束,中间是一小段 TOML,全部以#注释的形式存在,所以老解释器拿到这文件也不会报语法错误;requires-python声明 Python 版本要求,uv 发现本机不满足时会自动下载对应版本;- 依赖写法和 pyproject.toml 完全一致,支持版本约束(比如上面的
"requests<3")。
嫌手动维护注释麻烦?uv 两条命令帮你写:
uv init --script peps.py --python 3.12 # 给已有脚本补上头部骨架
uv add --script peps.py "requests<3" "rich" # 把依赖写进头部注释uv add --script 会自动把依赖追加进那块注释;要删某个依赖,直接编辑注释就行——它就是普通文本,没有任何黑魔法。
四、连 python 都不用敲:shebang 一步到位
Linux 的老传统可以和 PEP 723 无缝衔接。在脚本第一行加上 shebang:
#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.10"
# dependencies = ["httpx"]
# ///
import httpx
resp = httpx.get("https://example.com", timeout=10)
print(resp.status_code, resp.headers.get("server"))然后赋权执行:
chmod +x fetch.py
./fetch.py到这里,这个文件在装了 uv 的机器上就是一个货真价实的「可执行程序」——依赖自述、环境自建、拿走就能跑。env -S 的作用是把后面整串当作一条命令传给 uv,Linux 和近几年的 macOS 都原生支持。
五、uvx:顺手把别人的工具也拿了
uv 还附赠一个 uvx 命令,用来临时运行 PyPI 上任何命令行工具,不装进任何环境:
uvx ruff format . # 顺手格式化一下当前目录
uvx cowsay "ship it" # 经典终端彩蛋这种「用完即走」的用法特别适合偶尔用一次的工具和 CI 脚本——不用关心它装在哪、会不会跟别的项目打架。
六、边界感:什么时候不该用
单文件脚本 + PEP 723 的甜区很明确:一两百行以内、依赖简单、独立分发。一旦出现下面这些信号,就该升级成正式的 uv 项目(uv init 一个目录,走 pyproject.toml + lockfile 那套):
- 代码超过几百行,需要拆模块、写测试;
- 依赖里有本地路径包或 Git 仓库依赖;
- 需要锁定完整依赖树,保证团队/服务器环境严格一致——PEP 723 只声明直接依赖,不做完整锁定的传递依赖解析;
- 要打包发布到 PyPI。
小脚本用注释,正经项目上 lockfile,两者并不冲突。
写在最后
回顾一下这套组合拳:
- 痛点:发脚本 = 发脚本 + 发 requirements.txt + 发环境说明;
- PEP 723:把依赖和 Python 版本要求写进文件头部的标准注释块;
- uv:
uv run自动建环境装依赖,uv add --script免手写,shebang 让脚本直接可执行,uvx临时跑别人的工具。
下次再有人问「这个脚本怎么跑」,你可以只回一个字:先装 uv。剩下的,文件自己会说。
以上内容为 GLM 5.3 Agent 整合定时发布。

