HPC集群SLURM运行Jupyter中Matplotlib PGF/LaTeX后端找不到article.cls问题

架构老林

2026-10-6

问题本质

你遇到的问题核心是TeX Live的运行时环境变量没有被SLURM启动的Jupyter内核正确继承：kpsewhich定位article.cls这类TeX类文件不依赖PATH，而是依赖TeX Live专属的环境变量（比如TEXMFROOT、TEXINPUTS、TEXMFDIST等）。你终端里的变量是shell配置文件（比如.bashrc、.bash_profile）加载的，但SLURM启动任务、Jupyter内核初始化的时候默认不会加载交互式shell的配置，导致变量缺失。

解决方案

方案1：SLURM提交脚本中预加载TeX Live环境（最稳妥）

在你提交Jupyter任务的SLURM脚本里，先加载本地TeX Live的所有环境变量，再启动Jupyter：

# 加载本地TeX Live的环境变量，替换为你实际安装路径下的对应文件路径
source ~/.local/texlive/202*/texmf-dist/web2c/texmf.sh
# 若你通过tlmgr管理安装，也可以直接用tlmgr生成环境变量
eval $(~/.local/texlive/bin/x86_64-linux/tlmgr path add)
# 确认变量生效（可选，用于排障）
echo $TEXMFROOT >> slurm_tex_debug.log
# 之后再写启动Jupyter的命令

提交任务后Jupyter内核会继承SLURM任务的所有环境变量，就能正确找到TeX类文件。

方案2：Notebook代码开头手动注入环境变量

如果不方便修改SLURM提交脚本，可以直接在绘图代码的开头，用Python提前把TeX相关的环境变量注入当前进程：

import os
import subprocess

# 替换为你实际的TeX Live bin路径
tex_bin_path = os.path.expanduser("~/.local/texlive/bin/x86_64-linux")
os.environ["PATH"] = f"{tex_bin_path}:{os.environ['PATH']}"

# 加载texmf环境变量，把输出的变量直接注入当前进程
texmf_root = subprocess.run(
    [os.path.join(tex_bin_path, "kpsewhich"), "--expand-var", "$TEXMFROOT"],
    capture_output=True, text=True
).stdout.strip()
os.environ["TEXMFROOT"] = texmf_root

# 也可以直接把你终端中`env | grep ^TEX`输出的所有TEX开头的变量，都用os.environ设置，一劳永逸

注入完成后再运行绘图代码即可。

方案3：配置Jupyter内核的启动环境

你也可以直接修改用户目录下的Jupyter内核配置，让内核启动时自动加载TeX环境：

在终端运行jupyter kernelspec list，找到对应Python内核的存储文件夹
打开文件夹里的kernel.json文件，修改env字段添加所有TeX相关的环境变量，示例：

{
 "argv": [
  "python",
  "-m",
  "ipykernel_launcher",
  "-f",
  "{connection_file}"
 ],
 "display_name": "Python 3 (with TeX Live)",
 "language": "python",
 "env": {
  "PATH": "/home/你的用户名/.local/texlive/bin/x86_64-linux:${PATH}",
  "TEXMFROOT": "/home/你的用户名/.local/texlive/2024/texmf-dist",
  "TEXMFCNF": "/home/你的用户名/.local/texlive/2024/texmf-dist/web2c"
 }
}

修改保存后重启Jupyter服务，选择对应内核运行代码即可。

验证方法

配置完成后可以在Notebook里运行以下代码验证是否正常：

import subprocess
print(subprocess.run(["kpsewhich", "article.cls"], capture_output=True, text=True).stdout)

如果正常输出article.cls的绝对路径就说明配置生效。

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