Jupyter Notebook在Kaggle/GitHub渲染失败：未用widget却报metadata.widgets缺失state

问题原因 #

哪怕你没主动使用ipywidgets，部分Hugging Face相关库（比如transformers或其依赖工具）可能在后台悄悄给笔记本元数据添加了metadata.widgets字段，但未填充要求的state键，导致GitHub和Kaggle的渲染工具报错。

直接解决方法：清理无效元数据 #

方式1：手动修改笔记本元数据

1. 打开目标.ipynb文件，点击顶部菜单栏的Edit → Edit Notebook Metadata
2. 在弹出的JSON编辑器中，找到metadata下的"widgets"节点
3. 删除整个"widgets"字段，点击Save保存元数据
4. 重启内核、清除所有输出后，重新保存笔记本再推送到GitHub/上传到Kaggle

方式2：用脚本批量清理

如果有多个笔记本需要处理，用Python脚本自动移除无效元数据更高效：

import nbformat

# 读取原笔记本文件
with open("your_notebook.ipynb", "r", encoding="utf-8") as f:
    nb = nbformat.read(f, as_version=4)

# 删除widgets元数据节点
if "widgets" in nb.metadata:
    del nb.metadata["widgets"]

# 保存清理后的文件
with open("cleaned_notebook.ipynb", "w", encoding="utf-8") as f:
    nbformat.write(nb, f)

运行脚本后，用生成的cleaned_notebook.ipynb替换原文件即可。

Kaggle不稳定问题的额外处理 #

Kaggle的异常表现大概率也是元数据问题导致的，清理完widgets字段后：

• 上传前务必重启内核并清除所有输出
• 尽量避免在Kaggle中直接编辑后立刻推送，建议本地清理完成后再上传

预防手段 #

在使用Hugging Face库的笔记本开头添加这段代码，可避免后台自动生成widgets元数据：

# 禁用Jupyter自动生成widgets元数据
import os
os.environ['DISABLE_JUPYTER_WIDGETS'] = '1'

内容的提问来源于stack exchange，提问作者Rawan Alwadeya