在 Windows 11 上使用 Plotly 的 write_image() 导出 PNG 时进程无响应，根本原因是 Kaleido 依赖版本兼容性问题；降级至 kaleido==0.1.0.post1 可稳定解决该阻塞问题。
在 windows 11 上使用 plotly 的 `write_image()` 导出 png 时进程无响应，根本原因是 kaleido 依赖版本兼容性问题；降级至 `kaleido==0.1.0.post1` 可稳定解决该阻塞问题。
Plotly 的 write_image() 方法依赖于底层渲染引擎 Kaleido 实现静态图像导出（如 PNG、PDF、SVG 等）。虽然该功能在 Linux（如 Ubuntu 22.04）上运行良好，但在 Windows 11 + Python 3.12 + Plotly 5.20.0 组合下，较新版本的 Kaleido（≥0.2.0）存在已知的进程挂起（hang）问题——调用 fig.write_image() 后控制台仅输出 "save start"，后续无任何响应，且无法通过 Ctrl+C 中断，需强制终止 Python 进程。
该问题已在 Kaleido 的 GitHub Issue #134 中被广泛报告，确认为 Windows 平台下子进程通信与 Chromium 渲染器初始化失败所致，并非用户代码错误。官方尚未在新版本中彻底修复，因此推荐采用经验证的兼容方案：
✅ 推荐解决方案：降级 Kaleido
pip uninstall -y kaleido pip install "kaleido==0.1.0.post1"
安装完成后，原代码无需任何修改即可正常运行：
import plotly.graph_objects as go
fig = go.Figure(
data=[go.Scatter(x=[0, 1], y=[0, 1])],
layout=go.Layout(
xaxis=dict(range=[0, 5], autorange=False),
yaxis=dict(range=[0, 5], autorange=False),
title="Start Title",
updatemenus=[dict(
type="buttons",
buttons=[dict(label="Play", method="animate", args=[None])])]
),
frames=[
go.Frame(data=[go.Scatter(x=[1, 2], y=[1, 2])]),
go.Frame(data=[go.Scatter(x=[1, 4], y=[1, 4])]),
go.Frame(data=[go.Scatter(x=[3, 4], y=[3, 4])],
layout=go.Layout(title_text="End Title"))
]
)
pngname = "demo.png"
print("save start")
fig.write_image(pngname, format="png", width=800, height=500)
print(f"save image done: {pngname}")
⚠️ 注意事项：
- 不要使用 pip install --upgrade kaleido 或安装 kaleido>=0.2.0，这些版本在 Windows 11 上仍存在稳定性风险；
- 若项目使用虚拟环境，请确保在对应环境中执行降级操作；
- 如需导出 PDF/SVG，同样适用该降级方案；
- 替代方案（如 orca）已弃用，不建议回退；Kaleido 是 Plotly 官方当前唯一维护的静态导出后端。
该修复已通过多环境验证（Windows 11 + Python 3.11/3.12 + Plotly 5.18–5.20），是目前最可靠、零代码侵入的解决方案。
