Introduction

The Portable Graphics Format (PGF) is a language for producing vector graphics within TeX documents. There is also a higher-level language TikZ (TikZ ist kein Zeichenprogramm -- TikZ is not a drawing program) which uses PGF.

Since version 1.2, the Python plotting library Matplotlib has included a PGF backend to generate figures ready for inclusion in a TeX document. In order to get consistent figures that fit with the style of the document, this requires some configuration. The aim of pgfutils is to simplify this configuration and allow figures to be easily generated from a Python script.

The module provides two functions which set up and then save the figure. The actual plotting is performed by standard Matplotlib functions. For example, to generate a plot showing the 1st, 3rd, 5th, 7th, 9th and 11th harmonics of an ideal square wave and the resulting sum:

# Set up the figure environment.
from pgfutils import setup_figure, save
setup_figure(width=0.9, height=0.4)

import numpy as np
from matplotlib import pyplot as plt

# Generate square wave from a few terms of its Fourier series.
f = 3
t = np.linspace(0, 1, 501)
square = np.zeros(t.shape)
for n in range(1, 12, 2):
    # Create this harmonic and plot it as a dashed
    # partially-transparent line.
    component = np.sin(2 * n * np.pi * f * t) / n
    plt.plot(t, component, '--', alpha=0.4)

    # Add it to the overall signal.
    square += component

# Scale the final sum.
square *= 4 / np.pi

# Plot and label the figure.
plt.plot(t, square, 'C0')
plt.xlim(0, 1)
plt.ylim(-1.2, 1.2)
plt.xlabel("Time (s)")
plt.ylabel("Amplitude (V)")

# Save as a PGF image.
save()

Requirements

pgfutils follows SPEC0 when determining supported Python versions. Any minor version of Python released within the 3 years prior to a pgfutils release is supported. As of April 2026, this means Python 3.12 or later.

The only required external dependency is Matplotlib. Also following SPEC0, any minor version of Matplotlib which was first released within the 24 months prior to a pgfutils release is supported. As of April 2026, this means Matplotlib 3.9.0 or later.

The continuous integration testing checks the combinations of supported Python and Matplotlib version. Older versions of Python or Matplotlib may work, but are not tested and are not supported.

Examples

pgfutils comes with some examples which demonstrate its usage and integration into a build system. Depending on your installation method, these may be present somewhere in your filesystem (e.g., on a Linux system, they might be at /usr/share/matplotlib-pgfutils/examples). They can also be found in the data/share/matplotlib-pgfutils/examples directory of the source or online in the GitHub repository.

License

pgfutils is released under the three-clause BSD license. The terms of this license can be found in the LICENSE file in the source, or online at https://opensource.org/licenses/BSD-3-Clause

The Cotham Sans font used in some unit tests is copyright (c) 2015 Sebastien Sanfilippo and is licensed under the SIL Open Font License, Version 1.1. The license can be found in the source at tests/sources/fonts/Cotham/OFL.txt or online at https://scripts.sil.org/OFL and the font itself can be found at https://github.com/sebsan/Cotham

pgfutils supports the REUSE initiative. All files either have with SPDX-compliant license identifiers in their headers, or have a REUSE.toml manifest file accompanying them.