matplotlib/matplotlib · error · PlotError

The filename-prefix {output_base!r} is used multipletimes (i

Error message

The filename-prefix {output_base!r} is used multipletimes (it is also used in {env.doc2path(d)}).

What it means

Same uniqueness rule as the in-document check, but this branch fires when the filename-prefix was already registered by a different document; the message names the other file via env.doc2path(d). Because all generated plot images land in a shared build location, identical prefixes across documents would overwrite each other, so the build stops. Note the message text runs 'multipletimes' together (missing space) - useful when grepping build logs.

Source

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

        else:
            raise ExtensionError(f'srcset argument {entry!r} is invalid.')
    return srcset


def check_output_base_name(env, output_base):
    docname = env.docname

    if '.' in output_base or '/' in output_base or '\\' in output_base:
        raise PlotError(
            f"The filename-prefix '{output_base}' is invalid. "
            f"It must not contain dots or slashes.")

    for d in env.mpl_plot_image_basenames:
        if output_base in env.mpl_plot_image_basenames[d]:
            if d == docname:
                raise PlotError(
                    f"The filename-prefix {output_base!r} is used multiple times.")
            raise PlotError(f"The filename-prefix {output_base!r} is used multiple"
                            f"times (it is also used in {env.doc2path(d)}).")

    env.mpl_plot_image_basenames[docname].add(output_base)


def render_figures(code, code_path, output_dir, output_base, context,
                   function_name, config, context_reset=False,
                   close_figs=False,
                   code_includes=None):
    """
    Run a pyplot script and save the images in *output_dir*.

    Save the images under *output_dir* with file names derived from
    *output_base*
    """

    if function_name is not None:
        output_base = f'{output_base}_{function_name}'

View on GitHub (pinned to b379c1b69e)

Solutions

1. Make prefixes globally unique - include the doc slug: :filename-prefix: users-plot-
2. Prefer automatic naming by omitting :filename-prefix:
3. Audit the sources: grep -rn 'filename-prefix:' docs/ and de-duplicate

Example fix

# before (two different .rst files)
:filename-prefix: plot-   # in doc_a.rst and doc_b.rst -> collision

# after
doc_a.rst: :filename-prefix: intro-plot-
doc_b.rst: :filename-prefix: api-plot-

# pre-build check: no prefix reused across documents
import glob, re
from collections import Counter

counts = Counter()
for path in glob.glob('docs/**/*.rst', recursive=True):
    text = open(path).read()
    for m in re.finditer(r':filename-prefix:\s*(\S+):', text):
        counts[m.group(1)] += 1
dups = [p for p, n in counts.items() if n > 1]
assert not dups, f'filename-prefix values used more than once: {dups}'

When it happens

Trigger: Two .rst files (e.g. a users guide and an API tutorial) each containing a .. plot:: with the same :filename-prefix: plot-; shared RST include snippets that carry a hardcoded prefix and are included from several pages.

Common situations: Docs split into chapters that reuse example templates; shared includes with fixed prefixes; prefixes that were unique until a new page copied an existing block.

Related errors

• The filename-prefix {output_base!r} is used multiple times.
• The filename-prefix '{output_base}' is invalid. It must not
• invalid image format "%r" in plot_formats
• {arg!r} unknown boolean
• Argument should be None or 'reset' or 'close-figs'

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