Matplotlib显示中文标签遇Glyph缺失、字体未找到报错，求解决方案

问题场景 #

使用Matplotlib 3.5.3绘制带中文标签的图表时，因字体缺失导致中文无法正常渲染，相关代码及错误信息如下：

字体配置代码

import matplotlib
matplotlib.rcParams['font.family'] = ['Source Han Sans TW', 'sans-serif']
matplotlib.__version__  # 3.5.3

绘图代码

import math
from matplotlib import pyplot as plt

size = math.ceil(len(df_attr)** (1/2))
fig = plt.figure()

for i, col in enumerate(df_attr):
    fig.add_subplot(size, size, i + 1)
    df_template_income_tax[col].value_counts().plot(kind="bar", ax=plt.gca(), title=df_attr_eng[i], rot=0)

fig.tight_layout()

错误信息

findfont: Font family ['sans-serif'] not found. Falling back to DejaVu Sans.
findfont: Generic family 'sans-serif' not found because none of the following families were found: SimHei
/opt/microsoft/mlserver/9.4.7/runtime/python/lib/python3.7/site-packages/ipykernel_launcher.py:13: UserWarning: Glyph 25293 (\N{CJK UNIFIED IDEOGRAPH-62CD}) missing from current font.

解决方案 #

1. 安装支持中文的字体

你指定的Source Han Sans TW（繁体思源黑体）在当前环境中未安装，导致Matplotlib无法匹配字体， fallback到无中文支持的DejaVu Sans。

• Linux环境：通过包管理器安装通用中文字体包：

  # Debian/Ubuntu 系列
  sudo apt install fonts-noto-cjk
  # RHEL/CentOS 系列
  sudo yum install google-noto-cjk-fonts
  

• Windows/macOS环境：直接下载安装Source Han Sans TW或其他常用中文字体（如SimHei、Microsoft YaHei）。

2. 验证字体并修正配置

确保配置的字体名称与系统中已安装的字体完全匹配，可通过以下代码列出可用中文字体：

import matplotlib.font_manager as fm
for font in fm.fontManager.ttflist:
    if 'Source Han' in font.name or 'SimHei' in font.name:
        print(font.name)

根据输出的准确名称修改配置，同时建议关闭负号的Unicode渲染（避免负号显示异常）：

import matplotlib
matplotlib.rcParams['font.family'] = ['Source Han Sans TW', 'sans-serif']
matplotlib.rcParams['axes.unicode_minus'] = False

3. 直接指定本地字体文件（无全局安装权限时）

若无法在系统中安装字体，可直接加载本地字体文件并在绘图时指定：

import matplotlib.font_manager as fm
import matplotlib.pyplot as plt

# 替换为你的字体文件路径
font_path = '/path/to/SourceHanSansTW-Regular.otf'
font_prop = fm.FontProperties(fname=font_path)

size = math.ceil(len(df_attr)** (1/2))
fig = plt.figure()

for i, col in enumerate(df_attr):
    ax = fig.add_subplot(size, size, i + 1)
    df_template_income_tax[col].value_counts().plot(kind="bar", ax=ax, rot=0)
    # 为标题、坐标轴标签指定字体
    ax.set_title(df_attr_eng[i], fontproperties=font_prop)
    ax.set_xlabel('X轴名称', fontproperties=font_prop)
    ax.set_ylabel('计数', fontproperties=font_prop)

fig.tight_layout()

4. 清除Matplotlib字体缓存

若安装字体后仍无法识别，删除Matplotlib的字体缓存目录，让其重新扫描系统字体：

• Linux：删除 ~/.cache/matplotlib 目录
• Windows：删除 C:\Users\<用户名>\.matplotlib\ 下的字体缓存文件（如fontlist-v330.json）
• macOS：删除 ~/Library/Caches/matplotlib 目录

内容的提问来源于stack exchange，提问作者Jimmy Wang