nschloe/tikzplotlib · 上手攻略

• 仓库：nschloe/tikzplotlib
• 链接：https://github.com/nschloe/tikzplotlib
• 分类：学术写作 · 可视化
• 作者：Tom
• 更新：2026-08-20

是什么

tikzplotlib 是一个 Python 工具，用于将 matplotlib 生成的图表导出为 PGFPlots（PGF/TikZ）格式，从而可以原生嵌入 LaTeX 或 ConTeXt 文档。它最初叫 matplotlib2tikz，后来更名为 tikzplotlib，当前由 Nico Schlömer（nschloe）维护。

它的核心价值在于：matplotlib 画图，LaTeX 排版，两件事各干各的，但输出无缝衔接。

解决什么问题

写学术论文时，很多人用 matplotlib 生成图表然后导出 PDF 嵌入 LaTeX，但这样做有两个常见痛点：

1. 字体不统一：matplotlib 生成的 PDF 里字体和 LaTeX 正文的字体（Times New Roman、Computer Modern 等）不匹配，放在一起很违和。
2. 可编辑性差：PDF 里的数据点是「死」的，无法在 LaTeX 端修改线条粗细、坐标轴标签、图例位置。

tikzplotlib 把 matplotlib 的 figure 变成 PGFPlots 代码——PGFPlots 是 LaTeX 的图表库，输出的 .tex 文件里是纯文本的坐标轴、曲线数据、样式参数。在 LaTeX 文档里 \input{myfig.tex} 之后，整张图的字体、配色就跟 LaTeX 文档完全一致，且任何样式参数都可以直接在 LaTeX 端改。

快速安装

pip install tikzplotlib

测试是否安装成功：

python3 -c "import tikzplotlib; print(tikzplotlib.__version__)"

从源码运行测试（需要 pytest）：

git clone https://github.com/nschloe/tikzplotlib.git
cd tikzplotlib
pip install -e .
pytest

⚠️ Python 版本：建议 Python 3.8+。3D 绘图不支持（见下文坑）。

核心用法

最简工作流（三步）

Step 1：用 matplotlib 画图

import matplotlib.pyplot as plt
import numpy as np

plt.style.use("ggplot")
t = np.arange(0.0, 2.0, 0.1)
s = np.sin(2 * np.pi * t)
s2 = np.cos(2 * np.pi * t)
plt.plot(t, s, "o-", lw=4.1, label="sin")
plt.plot(t, s2, "o-", lw=4.1, label="cos")
plt.xlabel("time (s)")
plt.ylabel("Voltage (mV)")
plt.title("Simple plot $\\frac{\\alpha}{2}$")
plt.grid(True)
plt.legend()

Step 2：导出为 TikZ

import tikzplotlib

tikzplotlib.save("myplot.tex")
# 或获取字符串：
# code = tikzplotlib.get_tikz_code()

Step 3：在 LaTeX 文档里引用

\documentclass{article}
\usepackage[utf8]{inputenc}
\usepackage{pgfplots}
\usepgfplotslibrary{groupplots,dateplot}
\usetikzlibrary{patterns,shapes.arrows}
\pgfplotsset{compat=newest}

\begin{document}
\input{myplot.tex}
\end{document}

清理优化（可选）

导出不希望渲染在图外的点（超出坐标轴范围的数据点会被 PGFPlots 照常渲染），可以用 clean_figure() 先处理：

import tikzplotlib
tikzplotlib.clean_figure()  # 移除视野外点、简化曲线、降低点密度
tikzplotlib.save("myplot.tex")

进阶：指定目标分辨率

tikzplotlib.save(
    "myplot.tex",
    extra_axis_parameters=["width=\\textwidth"],
    override_externals=True,
    tex_relative_path_to_data="figures/"
)

ConTeXt 模式

tikzplotlib.save("myplot.tex", flavor="context")

对应的 ConTeXt 预置命令：

\setupcolors[state=start]
\usemodule[tikz]
\usemodule[pgfplots]
\usepgfplotslibrary[groupplots,dateplot]
\usetikzlibrary[patterns,shapes.arrows]
\pgfplotsset{compat=newest}

或者直接用 tikzplotlib.Flavors.latex.preamble() / tikzplotlib.Flavors.context.preamble() 打印出所需的包声明。

典型适用场景

• 学术论文图表：理工科期刊投稿要求图表风格与正文一致，tikzplotlib 是最省事的方案
• 博士论文/学位论文：需要批量图表风格统一，手动调 matplotlib 参数 vs. LaTeX 端统一样式，前者更灵活
• 幻灯片（Beamer）：同样要求字体/风格统一，且 Beamer 支持直接 input .tex 图
• 需要后续在 LaTeX 里微调的图：比如评审让你「把图例字体调小一点」，不用回 Python，直接改 .tex 文件里的参数

坑与注意

⚠️ 3D 绘图不支持：matplotlib 的 3D 图表（Axes3D）无法转换为 PGFPlots，这是上游已知限制（matplotlib 本身对 3D 输出的 PGF/TikZ 后端支持就不完整）。如果必须用 3D 图，这工具不适用。

⚠️ 非连续型图表限制较多：热力图（heatmap）、填充图（filled contour）以及某些复杂组合图在转换后可能出现样式偏差，需要手动调整 PGFPlots 参数。

⚠️ 线条宽度/透明度等可能失真：matplotlib 的某些 style 参数（如半透明 scatter）在 PGFPlots 里需要用 \addplot 的 opacity 或 draw opacity 显式声明，导出后检查一下 .tex 文件。

⚠️ 数据点数量多时 .tex 文件体积大：如果 matplotlib 图里本身有几万个小数据点，生成的 .tex 文件可能很臃肿。用 clean_figure() 预清理是减少体积的关键。

⚠️ LaTeX 编译时间：大量 tikzplotlib 生成的图会显著增加 LaTeX 编译时间（PDFLaTeX 需要处理所有 TikZ 指令），论文图表多的时候考虑用 standalone 类单独编译图再 PDF 嵌入。

⚠️ 包名变化：此包曾用名 matplotlib2tikz，如果看到老文章提到这个名字，指的是同一个东西。

与同类对比

核心差异：tikzplotlib 输出的是 PGFPlots 而非原始 PGF/TikZ。PGFPlots 是更高层的抽象，用 axis / addplot / grid 这种声明式语法，比手写 raw TikZ 更易读、更易改，也更能保留 matplotlib 的轴标签、刻度、网格等元数据。

一句话推荐结论

写学术论文或学位论文需要图表与 LaTeX 完美融合时，tikzplotlib 是 Python 生态里最成熟的解法；只要你的图不是 3D 的且数据量不是天文数字，它基本能做到「matplotlib 画图 → 一行命令 → LaTeX 无缝嵌入」。

来源

• https://github.com/nschloe/tikzplotlib（README、示例代码）
• https://pypi.org/project/tikzplotlib/（PyPI 页面）
• https://gt.rstudio.com/news/index.html（参考 CRAN 时间线做版本参照）
• https://www.ctan.org/pkg/pgfplots（PGFPlots 官方文档）