Jupyter Notebook中Python绘图不显示图像的解决方法

在 Jupyter Notebook 中编写并运行 Python 数据可视化代码时，最常见的阻碍之一是：执行完绘图单元格后，页面只打印出类似 <Figure size 640x480 with 1 Axes> 的对象描述文本，或者单元格下方完全空白、没有任何图像呈现。这一现象并非 Python 解释器或代码逻辑出现语法错误，通常是由 Matplotlib 绘图后端的绑定模式、单元格执行模式（交互式与非交互式），以及 IPython 内核与前端展示层之间的通信机制决定的。本文系统梳理该问题的常见表现、底层原因及针对性解决方法，帮助读者建立标准稳定的绘图配置习惯。

图 1：Jupyter Notebook 绘图不显示问题的常见表现与处理路径

一、原因排查与核心解决步骤

排查绘图不显示的问题，应遵循由浅入深的顺序。多数情况下是由最基础的命令调用缺失引起的，少数情况下由运行环境或底层图形后端异常导致。

1. 单元格仅返回对象文本，缺少显式渲染调用

在常规 Python 交互式命令行中，如果不写 plt.show()，往往不会弹出图形窗口。在 Jupyter Notebook 中，如果最后一个表达式返回的是一个 Matplotlib 对象（如 <Axes: > 或 <Figure size ...>），IPython 默认行为是打印该对象的 __repr__ 字符串。如果在某些特定版本或非内联模式下，图形事件未被挂载，页面就只会显示这一行文字。

解决方法：在单元格最末尾显式添加 plt.show()，或在最后一行代码结尾添加分号 ;。添加分号的作用是抑制行末表达式的文本返回值，强制让 IPython 仅展示绘图渲染结果：

import matplotlib.pyplot as plt
import numpy as np

x = np.linspace(0, 10, 100)
y = np.sin(x)

# 方式一：显式调用 plt.show()
plt.plot(x, y)
plt.title("正弦函数示例")
plt.show()

# 方式二：在绘图函数后加分号抑制对象文本输出
# plt.plot(x, y);

2. 未配置内联渲染模式（%matplotlib inline）

这是 Jupyter 初学者最常遭遇的情况。Jupyter Notebook 支持多种图形呈现方式：可以将图表以静态图片（PNG/SVG）嵌入在单元格正下方，也可以通过独立窗口弹出（如使用 Qt、Tkinter 交互式窗口）。如果当前环境默认启用了外部窗口后端，而在没有图形界面的远程服务器、Docker 容器或未正确配置 X11 转发的环境中运行，程序会尝试寻找外部显示服务（Display），最终因超时或静默失败导致单元格没有任何输出。

解决方法：在 Notebook 最顶部的单元格中显式加入 IPython 提供的魔术命令 %matplotlib inline。该命令会通知 IPython 内核，将 Matplotlib 的渲染后端重定向为内联后端（matplotlib_inline.backend_inline），所有图形都将转为静态流直接嵌入网页 DOM：

# 在 Notebook 最顶部单元格运行，设置全局内联渲染
%matplotlib inline

import matplotlib.pyplot as plt

# 随后正常进行绘图
plt.figure(figsize=(8, 4))
plt.plot([1, 2, 3, 4], [10, 20, 25, 30])
plt.show()

二、Jupyter 与 Matplotlib 后端交互机制

为了从根本上理解为什么图像有时无法呈现，需要了解 Matplotlib 与 Jupyter 之间的架构分层。Matplotlib 自身由两层构成：上层是面向用户的绘图接口（如 pyplot 和各种 Artist 图形元素），下层则是负责具体像素绘制与窗口呈现的后端（Backend）。

图 2：Matplotlib 画布对象经由内核后端向前端 DOM 传递的生命周期

从上图可知，在 Notebook 环境中绘图，核心必须确保使用内联光栅化后端（如 Agg 或 inline）。如果后端被错误配置为系统桌面后端，绘图指令就会发往操作系统，而无法打包成数据流推送到网页前端。

三、进阶场景：循环输出与多图绘制失效

在批量处理数据或训练模型的场景中，我们经常需要在 for 循环中为每个批次或每个类别生成图表。许多人会发现：在循环中写了多次 plt.plot()，结果单元格最终只输出了最后一张图，或者前面的图全部被覆盖折叠。

这是因为在默认情况下，IPython 仅在整个单元格执行完成（Post-execution）时，触发一次自动收集并展示当前活跃的 Figure。在循环内部，如果不主动通知前端进行渲染，同一个画布会被反复重用，最终只展示最后的状态。

标准解决方案：使用 IPython.display 提供的 display() 函数在循环内部主动分发渲染事件，并配合 plt.close() 及时关闭画布，避免内存泄漏：

import matplotlib.pyplot as plt
import numpy as np
from IPython.display import display

# 模拟需要批量绘制三组独立数据
categories = ['类别 A', '类别 B', '类别 C']

for cat in categories:
    fig, ax = plt.subplots(figsize=(6, 3))
    data = np.random.randn(50).cumsum()
    ax.plot(data, label=cat, color='#52677D')
    ax.set_title(f"数据追踪 - {cat}")
    ax.legend()
    
    # 主动向前端输出当前图表
    display(fig)
    
    # 关闭当前画布，释放内核内存并防止重叠
    plt.close(fig)

图 3：常见绘图故障特征、根因与修复命令对照表

四、环境依赖冲突与底层排查技巧

如果执行了 plt.show() 和 %matplotlib inline 之后依然无法显示图片，问题往往出现在 Python 环境的依赖包不一致或版本损坏上。此时可按以下步骤排查底层运行库：

1. 确认当前正在使用的 Backend

在单元格中执行以下代码，打印出当前运行内核实际挂载的后端名称：

import matplotlib
print("当前 Matplotlib 后端:", matplotlib.get_backend())

正常情况下，在标准 Jupyter Notebook 内联环境下，输出应该为：

当前 Matplotlib 后端: module://matplotlib_inline.backend_inline

如果输出结果是 TkAgg、Qt5Agg 或 MacOSX，说明内核依然绑定在本地 GUI 接口上。若通过魔术命令无法更改，可以在导入 pyplot 之前，强制使用纯渲染后端：

import matplotlib
matplotlib.use('Agg')  # 必须在 import matplotlib.pyplot 之前执行
import matplotlib.pyplot as plt

2. 修复 matplotlib-inline 扩展库

自 IPython 8.x 分离后，内联显示功能由独立的 matplotlib-inline 包提供支持。如果该包损坏或版本过旧，可能导致静默断联。可以在终端激活对应的虚拟环境，运行以下更新指令：

pip install --upgrade matplotlib matplotlib-inline ipykernel

安装完成后，务必在 Jupyter 页面顶部菜单点击 Kernel -> Restart Kernel，重启内核以重新加载共享库。

图 4：Jupyter Notebook 绘图异常排查决策树与执行指南

五、规范建议与最佳实践模板

为了在日常数据分析和学术研究中彻底避免绘图不显示的问题，建议在每个新创建的 Notebook 文档首个单元格中使用统一的标准初始化模板：

# ==============================
# Jupyter 绘图环境推荐初始化模板
# ==============================
%matplotlib inline

import matplotlib.pyplot as plt
import matplotlib as mpl

# 优化图像清晰度（适用于高分辨率屏 / Retina 显示屏）
%config InlineBackend.figure_format = 'retina'

# 解决中文字符与负号乱码（Windows/macOS/Linux 通用字体回退）
mpl.rcParams['font.sans-serif'] = ['PingFang SC', 'Microsoft YaHei', 'SimHei', 'Arial']
mpl.rcParams['axes.unicode_minus'] = False

# 统一默认画板尺寸与分辨率
mpl.rcParams['figure.figsize'] = (8, 4.5)
mpl.rcParams['figure.dpi'] = 100

通过遵循以上规范，显式声明内联后端、规范使用 plt.show() 及 display() 接口，即可确保在各类本地机器、远程云端与容器化 Jupyter 环境中稳定呈现高质量的数据图表。