linux设置matplotlib中文字体

中文显示为方框，通常是 Matplotlib 最终选中的字体不包含相应字形。先准备可用字体，再核对实际匹配结果，不要只更改一个字体名称。

步骤 1：准备或安装中文字体

如果已有 SimHei.ttf，可以放到项目的 fonts/ 目录。原记录中的 SimHei 文件链接 保留作参考；也可以使用自己已有的 Noto Sans CJK、思源黑体等中文字体文件，后续路径和字体名称应与实际文件一致。

方法一：只在当前 Python 进程注册字体

在项目目录运行：

from pathlib import Path
from matplotlib import font_manager as fm

font_path = Path("fonts/SimHei.ttf").resolve()
if not font_path.is_file():
    raise FileNotFoundError(f"请先准备字体文件: {font_path}")

fm.fontManager.addfont(str(font_path))
font_name = fm.FontProperties(fname=str(font_path)).get_name()
print("字体名称:", font_name)
print("匹配文件:", fm.findfont(font_name, fallback_to_default=False))

addfont() 不会永久保存到 Matplotlib 缓存，每次新的 Python 进程都需要调用。这种方法不要求把字体安装到操作系统中，适合项目携带字体的场景。

方法二：安装到 Linux 当前用户字体目录

下面假设下载的字体文件在当前目录，系统已有 fontconfig：

mkdir -p "$HOME/.local/share/fonts"
cp -i -- ./SimHei.ttf "$HOME/.local/share/fonts/SimHei.ttf"
fc-cache -f "$HOME/.local/share/fonts"
fc-match SimHei

cp -i 遇到同名文件会询问，不直接覆盖。安装完成后重启 Python 进程，并检查 fc-match 和 Matplotlib 返回的实际字体文件；不能把默认回退字体当作安装成功。

步骤 2：配置 Matplotlib 使用中文字体

下面给出完整绘图示例，放在项目目录运行，字体文件位于 fonts/SimHei.ttf。通过字体文件读取真实名称，避免安装 SimHei 却配置成 WenQuanYi Micro Hei：

from pathlib import Path
import matplotlib.pyplot as plt
from matplotlib import font_manager as fm
import pandas as pd

font_path = Path("fonts/SimHei.ttf").resolve()
if not font_path.is_file():
    raise FileNotFoundError(f"字体文件不存在: {font_path}")
fm.fontManager.addfont(str(font_path))
font_name = fm.FontProperties(fname=str(font_path)).get_name()

plt.rcParams["font.family"] = [font_name]
plt.rcParams["axes.unicode_minus"] = False

data = {
    "日期": ["2024-01-01", "2024-01-02", "2024-01-03"],
    "销售额": [150, 200, 250],
}
df = pd.DataFrame(data)

fig, ax = plt.subplots()
ax.plot(df["日期"], df["销售额"], marker="o")
ax.set_title("销售额趋势")
ax.set_xlabel("日期")
ax.set_ylabel("销售额")
ax.tick_params(axis="x", labelrotation=45)
fig.tight_layout()
plt.show()

服务器或无桌面的环境，可以在导入 pyplot 前选择 matplotlib.use("Agg")，并将最后一行改为 fig.savefig("sales.png", dpi=150)。已有同名输出时先另存，避免覆盖。

仍然不显示时怎么排查

import matplotlib
from matplotlib import font_manager as fm

print("配置目录:", matplotlib.get_configdir())
print("缓存目录:", matplotlib.get_cachedir())
print("当前配置文件:", matplotlib.matplotlib_fname())
for file in fm.findSystemFonts(fontext="ttf"):
    print(file)

确认程序使用的 Python 环境、字体文件与绘图进程一致。项目内直接 addfont() 通常无需清理字体缓存，也不必修改安装目录中的 matplotlibrc。要持久配置时，使用用户或项目配置文件，并确保指定字体在实际运行环境中存在。

参考

• Matplotlib 字体管理与 addfont