matplotlib/matplotlib · error · PlotError

invalid image format "%r" in plot_formats

Error message

invalid image format "%r" in plot_formats

What it means

The conf.py option plot_formats tells the plot directive which image formats to emit. Valid entries are plain strings ('png'), strings with dpi ('png:80'), or (suffix, dpi) tuples/lists of exactly length 2. Any other shape - a 3-element tuple, a bare int, a dict - raises PlotError inside get_plot_formats when the first plot is rendered.

Source

Thrown at lib/matplotlib/sphinxext/plot_directive.py:636

    matplotlib.rc_file_defaults()
    matplotlib.rcParams.update(plot_rcparams)


def get_plot_formats(config):
    default_dpi = {'png': 80, 'hires.png': 200, 'pdf': 200}
    formats = []
    plot_formats = config.plot_formats
    for fmt in plot_formats:
        if isinstance(fmt, str):
            if ':' in fmt:
                suffix, dpi = fmt.split(':')
                formats.append((str(suffix), int(dpi)))
            else:
                formats.append((fmt, default_dpi.get(fmt, 80)))
        elif isinstance(fmt, (tuple, list)) and len(fmt) == 2:
            formats.append((str(fmt[0]), int(fmt[1])))
        else:
            raise PlotError('invalid image format "%r" in plot_formats' % fmt)
    return formats


def _parse_srcset(entries):
    """
    Parse srcset for multiples...
    """
    srcset = {}
    for entry in entries:
        entry = entry.strip()
        if len(entry) >= 2:
            mult = entry[:-1]
            srcset[float(mult)] = entry
        else:
            raise ExtensionError(f'srcset argument {entry!r} is invalid.')
    return srcset

View on GitHub (pinned to b379c1b69e)

Solutions

1. Use plain strings: plot_formats = ['png', 'svg']
2. Or suffix:dpi strings: plot_formats = ['png:120']
3. Or 2-tuples: plot_formats = [('png', 120), ('svg', 90)]

Example fix

# conf.py before
plot_formats = [('png', 80, 'extra')]  # PlotError: invalid image format

# conf.py after
plot_formats = [('png', 80)]

def valid_plot_formats(fmts) -> bool:
    for f in fmts:
        if isinstance(f, str):
            continue
        if isinstance(f, (tuple, list)) and len(f) == 2:
            continue
        return False
    return True

# conf.py
plot_formats = ['png', ('svg', 90)]
assert valid_plot_formats(plot_formats), 'plot_formats entries must be str or (suffix, dpi) pairs'

def is_valid_plot_format_entry(f) -> bool:
    """True if get_plot_formats accepts this entry."""
    return isinstance(f, str) or (isinstance(f, (tuple, list)) and len(f) == 2)

When it happens

Trigger: plot_formats = [('png', 80, 'extra')] in conf.py; plot_formats = [100]; plot_formats = ['png', {'svg': 90}]; configs written for sphinx-gallery, whose plot_formats shape differs.

Common situations: Misreading the tuple arity or argument order; trying to attach extra per-format options; migrating conf.py between doc toolchains.

Understand the failure class

Background: Config validation failed: what "invalid value for {key}" and settings-rejection errors mean across 19 open-source libraries — this error's family across 19 libraries.

Related errors

• {err} `plot_working_directory` option in Sphinx configuratio
• {err} `plot_working_directory` option in Sphinx configuratio
• srcset argument {entry!r} is invalid.
• The filename-prefix '{output_base}' is invalid. It must not
• The filename-prefix {output_base!r} is used multiple times.

AI-assisted analysis of matplotlib/matplotlib@b379c1b69e (2026-08-21). Data as JSON: /api/errors/1daf64a67179761e. Report an issue: GitHub.