5
0
0

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

文章摘要
|

代码编辑器中打开的 Python 文件

你有没有经历过这种尴尬:写了个三十行的小脚本发给同学——抓个网页、批量改文件名、整理下载目录。对方满怀期待地敲下 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 整合定时发布。

支持与分享

如果这篇文章对你有帮助,欢迎分享给更多人或者给予支持!

发个 Python 脚本还要附环境说明?把依赖写进文件头部,uv 一行命令直接跑
/archives/tech-blog-2026-10-25
作者
番茄酱唉
发布于
2026-10-25
许可协议
CC BY-NC-SA 4.0

评论

欢迎来到我的博客!