In favour of


A Pandoc filter to include figures generated from Python code blocks

Version on this page:
LTS Haskell 16.31:
Stackage Nightly 2020-06-15:
Latest on Hackage:

See all snapshots pandoc-pyplot appears in

MIT licensed and maintained by Laurent P. René de Cotret
This version can be pinned in stack with:pandoc-pyplot-,3142

Module documentation for

pandoc-pyplot - A Pandoc filter to generate Matplotlib figures directly in documents

Hackage version Stackage version (LTS) Stackage version (nightly) Windows Build status macOS and Linux Build Status GitHub

pandoc-pyplot turns Python code present in your documents into embedded Matplotlib figures.



The filter recognizes code blocks with the .pyplot class present in Markdown documents. It will run the script in the associated code block in a Python interpreter and capture the generated Matplotlib figure.

Here is a basic example using the scripting matplotlib.pyplot API:

import matplotlib.pyplot as plt

plt.plot([0,1,2,3,4], [1,2,3,4,5])
plt.title('This is an example figure')

Putting the above in, we can then generate the plot and embed it:

pandoc --filter pandoc-pyplot --output output.html


pandoc --filter pandoc-pyplot --output output.pdf

or any other output format you want.


The filter works slightly differently in LaTeX documents. In LaTeX, the minted environment must be used, with the pyplot class.

import matplotlib.pyplot as plt

plt.plot([0,1,2,3,4], [1,2,3,4,5])
plt.title('This is an example figure')

Note that you do not need to have minted installed.


There are more examples in the source repository, in the \examples directory.



You can also specify a caption for your image. This is done using the optional caption parameter.


```{.pyplot caption="This is a simple figure"}
import matplotlib.pyplot as plt

plt.plot([0,1,2,3,4], [1,2,3,4,5])
plt.title('This is an example figure')


\begin{minted}[caption=This is a simple figure]{pyplot}
import matplotlib.pyplot as plt

plt.plot([0,1,2,3,4], [1,2,3,4,5])
plt.title('This is an example figure')

Caption formatting is either plain text or Markdown. LaTeX-style math is also support in captions (using dollar signs $…$).

Link to source code and high-resolution figure

In case of an output format that supports links (e.g. HTML), the embedded image generated by pandoc-pyplot will be a link to the source code which was used to generate the file. Therefore, other people can see what Python code was used to create your figures. A high resolution image will be made available in a caption link.

(New in version For cleaner output (e.g. PDF), you can turn this off via the links=false key:


```{.pyplot links=false}



or via a configuration file.

Including scripts

If you find yourself always repeating some steps, inclusion of scripts is possible using the include parameter. For example, if you want all plots to have the ggplot style, you can write a very short preamble like so:

import matplotlib.pyplot as plt'ggplot')

and include it in your document as follows:

plt.plot([0,1,2,3,4], [1,2,3,4,5])
plt.title('This is an example figure')

Which is equivalent to writing the following markdown:

import matplotlib.pyplot as plt'ggplot')

plt.plot([0,1,2,3,4], [1,2,3,4,5])
plt.title('This is an example figure')

The equivalent LaTeX usage is as follows:



This include parameter is perfect for longer documents with many plots. Simply define the style you want in a separate script! You can also import packages this way, or define functions you often use.

Customization of figures beyond what is available in pandoc-pyplot can also be done through the include script. For example, if you wanted to have transparent figures, you can do so via matplotlib.pyplot.rcParams:

import matplotlib.pyplot as plt

plt.rcParams['savefig.transparent'] = True

You can take a look at all available matplotlib parameters here.

No wasted work

pandoc-pyplot minimizes work, only generating figures if it absolutely must. Therefore, you can confidently run the filter on very large documents containing dozens of figures — like a book or a thesis — and only the figures which have recently changed will be re-generated.

Compatibility with pandoc-crossref

pandoc-crossref is a pandoc filter that makes it effortless to cross-reference objects in Markdown documents.

You can use pandoc-crossref in conjunction with pandoc-pyplot for the ultimate figure-making pipeline. You can combine both in a figure like so:

```{#fig:myexample .pyplot caption="This is a caption"}
# Insert figure script here

As you can see in @fig:myexample, ...

If the above source is located in file, you can render the figure and references by applying pandoc-pyplot first, and then pandoc-crossref. For example:

pandoc --filter pandoc-pyplot --filter pandoc-crossref -i -o myfile.html


(New in version To avoid repetition, pandoc-pyplot can be configured using simple YAML files. pandoc-pyplot will look for a .pandoc-pyplot.yml file in the current working directory:

# You can specify any or all of the following parameters
interpreter: python36
directory: mydirectory/
format: jpeg
links: false
dpi: 150
tight_bbox: true
transparent: false
flags: [-O, -Wignore]

These values override the default values, which are equivalent to:

# Defaults if no configuration is provided.
# Note that the default interpreter name on MacOS and Unix is 'python3'
# and 'python' on Windows.
interpreter: python
flags: []
directory: generated/
format: png
links: true
dpi: 80
tight_bbox: false
transparent: false
flags: []

Using pandoc-pyplot --write-example-config will write the default configuration to a file .pandoc-pyplot.yml, which you can then customize.

Configuration-only parameters

There are a few parameters that are only available via the configuration file .pandoc-pyplot.yml:

  • interpreter is the name of the interpreter to use. For example, interpreter: python36;
  • flags is a list of strings, which are flags that are passed to the python interpreter. For example, flags: [-O, -Wignore];
  • (New in version tight_bbox is a boolean that determines whether to use bbox_inches="tight" or not when saving Matplotlib figures. For example, tight_bbox: true. See here for details;
  • (New in version transparent is a boolean that determines whether to make figure background transparent or not. This is useful, for example, for displaying a plot on top of a colored background on a web page. High-resolution figures are not affected. For example, transparent: true.



Windows binaries are available on GitHub. Place the executable in a location that is in your PATH to be able to call it.

If you can show me how to generate binaries for other platform using e.g. Azure Pipelines, let me know!

Installers (Windows)

Windows installers are made available thanks to Inno Setup. You can download them from the release page.

From Hackage/Stackage

pandoc-pyplot is available on Hackage. Using the cabal-install tool:

cabal update
cabal install pandoc-pyplot

Similarly, pandoc-pyplot is available on Stackage:

stack update
stack install pandoc-pyplot

From source

Building from source can be done using stack or cabal:

git clone
cd pandoc-pylot
stack install # Alternatively, `cabal install`

Running the filter


This filter only works with the Matplotlib plotting library. Therefore, you a Python interpreter and at least Matplotlib installed. The name of the Python interpreter to use can be specified in a .pandoc-pyplot.yml file; by default, pandoc-pyplot will use the "python" name on Windows, and "python3" otherwise.

You can use the filter with Pandoc as follows:

pandoc --filter pandoc-pyplot --output output.html

In which case, the output is HTML. Another example with PDF output:

pandoc --filter pandoc-pyplot --output output.pdf

Python exceptions will be printed to screen in case of a problem.

pandoc-pyplot has a limited command-line interface. Take a look at the help available using the -h or --help argument:

pandoc-pyplot --help

Usage as a Haskell library

To include the functionality of pandoc-pyplot in a Haskell package, you can use the makePlot :: Block -> IO Block function (for single blocks) or plotTransform :: Pandoc -> IO Pandoc function (for entire documents).

Usage with Hakyll

This filter was originally designed to be used with Hakyll. In case you want to use the filter with your own Hakyll setup, you can use a transform function that works on entire documents:

import Text.Pandoc.Filter.Pyplot (plotTransform)

import Hakyll

-- Unsafe compiler is required because of the interaction
-- in IO (i.e. running an external Python script).
makePlotPandocCompiler :: Compiler (Item String)
makePlotPandocCompiler =
    (unsafeCompiler . plotTransform)

The plotTransformWithConfig is also available for a more configurable set-up.


Do not run this filter on unknown documents. There is nothing in pandoc-pyplot that can stop a Python script from performing evil actions.


Change log

pandoc-pyplot uses Semantic Versioning


  • Fixed an issue where setting the configuration option transparent: true left high-resolution figures difficult to see. Therefore, the option transparent: true does not affect high-resolution figures anymore.


  • Added support for two new configuration values: tight_bbox: true|false and transparent: true|false. These values are only supported via configuration files .pandoc-pyplot.yml.


  • Added examples and documentation on how to use pandoc-pyplot on LaTeX documents.

  • Allowed raw LaTeX macros in figure captions. This is required to label figures in LaTeX. E.g.:

  • with-links key changed to links. I’m sorry. Pandoc doesn’t support LaTeX tokens with -.


  • Switched to using optparse-applicative for command-line argument parsing.

  • Added a command-line options, “–write-example-config”, which will write a config file “.pandoc-pyplot.yml” to show all available configuration options.

  • Links to source code and high-res images can be suppressed using {.pyplot with-links=false ...} (or via the configuration file with with-links: false). This is to get cleaner output in technical documentation (e.g. PDF). Example:

      ```{.pyplot caption="This is a caption" with-links=false}
      import matplotlib.pyplot as plt
  • Added automated builds on macOS and Linux via Azure-Pipelines. Windows build will stay on Appveyor for now.


  • Added the “flags” configuration option, which allows to pass command-line flags to the Python interpreter. For example, warnings can be suppressed using the -Wignore flag.
  • Refactoring of the script check mechanism. It will be much easier to extend in the future.
  • Updated the command-line help with an example combining pandoc-pyplot and pandoc-crossref
  • Default Python interpreter is now “python” on Windows and “python3” otherwise.


  • Fixed a critical bug where pandoc-pyplot would interpret input from pandoc as a malformed command-line flag.


  • Added a command-line option to open the HTML manual in the default web browser.
  • Added documentation regarding compatibility with pandoc-crossref. This was always supported but not explicitly documented.


  • Fixed outdated documentation (referencing “target” parameter)
  • Fixed types required to build Configuration values that were not exported (SaveFormat, PythonScript)


  • Added support for config files “.pandoc-pyplot.yml”, which specify different default values. This is mirrored in the new Configuration type and new functions, makePlotWithConfig and plotTransformWithConfig.
  • Added the ability to specify a different Python interpreter to use.
  • Added support for GIF and TIF files.
  • Added the “-f”/”–formats” command to show supported output figure formats.
  • Added support for GHC 8.2
  • Moved internal modules to Text.Pandoc.Filter.Pyplot.Internal module.


  • Support for Markdown formatting in figure captions, including LaTeX math.


Many breaking changes in this release:

  • pandoc-pyplot will now determine the filename based on hashing the figure content. Therefore, figures will only be re-generated if necessary.
  • Removed the ability to control the filename and format directly using the plot_target=... attribute.
  • Added the ability to control the directory in which figures will be saved using the directory=... attribute.
  • Added the possibility to control the figures dots-per-inch (i.e. pixel density) with the dpi=... attribute.
  • Added the ability to control the figure format with the format=... attribute. Possible values are currently "png", "svg", "pdf", "jpg"/"jpeg" and "eps".
  • The confusing plot_alt=... attribute has been renamed to caption=... for obvious reasons.
  • The plot_include=... attribute has been renamed to include=....
  • Added the generation of a higher resolution figure for every figure pandoc-pyplot understands.


  • Added the ability to include Python files before code using the attribute.
  • Added a test suite.


  • Fixed an issue where pandoc-pyplot would not build with base < 4.9 (#1)


  • Added support for captions using the plot_alt=... attribute. For example:

      ```{plot_target=test.png plot_alt="This is a caption"}
      import matplotlib.pyplot as plt


  • Added plotTransform :: Pandoc -> IO Pandoc function to transform entire documents. This makes it easier to integrate pandoc-pyplot into Hakyll-based sites!


  • Updated README with fixes and warnings
  • Added top-level package documentation compatible with Haddock
  • Added Unsafe language extension, as this filter will run arbitrary Python scripts.


Initial release.

See documentation on Hackage