matplotlib/matplotlib · error · RuntimeError

Entry point name '{name}' is a built-in backend

Error message

Entry point name '{name}' is a built-in backend

What it means

When registering third-party backend entry points, matplotlib rejects names that collide with a built-in backend (checked against _BUILTIN_BACKEND_TO_GUI_FRAMEWORK). Allowing a plugin to claim e.g. 'agg' or 'qt5agg' would let it silently shadow or hijack a core backend, so registration raises this RuntimeError instead.

Source

Thrown at lib/matplotlib/backends/registry.py:178

                entries, "ipympl", (0, 9, 4), ["ipympl", "widget"],
                "ipympl.backend_nbagg")

        return entries

    def _validate_and_store_entry_points(self, entries):
        # Validate and store entry points so that they can be used via matplotlib.use()
        # in the normal manner. Entry point names cannot be of module:// format, cannot
        # shadow a built-in backend name, and there cannot be multiple entry points
        # with the same name but different modules. Multiple entry points with the same
        # name and value are permitted (it can sometimes happen outside of our control,
        # see https://github.com/matplotlib/matplotlib/issues/28367).
        for name, module in set(entries):
            name = name.lower()
            if name.startswith("module://"):
                raise RuntimeError(
                    f"Entry point name '{name}' cannot start with 'module://'")
            if name in self._BUILTIN_BACKEND_TO_GUI_FRAMEWORK:
                raise RuntimeError(f"Entry point name '{name}' is a built-in backend")
            if name in self._backend_to_gui_framework:
                raise RuntimeError(f"Entry point name '{name}' duplicated")

            self._name_to_module[name] = "module://" + module
            # Do not yet know backend GUI framework, determine it only when necessary.
            self._backend_to_gui_framework[name] = "unknown"

    def backend_for_gui_framework(self, framework):
        """
        Return the name of the backend corresponding to the specified GUI framework.

        Parameters
        ----------
        framework : str
            GUI framework such as "qt".

        Returns
        -------

View on GitHub (pinned to b379c1b69e)

Solutions

1. Rename the entry point to a unique name (e.g. 'myagg' instead of 'agg') in pyproject.toml/setup.cfg and keep the module path as the value
2. If you are a user hitting this from someone else's package, uninstall or upgrade it: pip uninstall <pkg>, and report the naming bug upstream
3. Confirm the fix by importing matplotlib and calling matplotlib.use('<new-unique-name>')

Example fix

# before (pyproject.toml)
[project.entry-points.'matplotlib.backends']
agg = 'myplugin.faster_agg'

# after
[project.entry-points.'matplotlib.backends']
faster-agg = 'myplugin.faster_agg'

BUILTIN = {'agg', 'pdf', 'ps', 'svg', 'template', 'cairo', 'gtk3agg',
           'gtk3cairo', 'gtk4agg', 'gtk4cairo', 'macosx', 'nbagg', 'notebook',
           'qt5agg', 'qt5cairo', 'qtagg', 'qtcairo', 'tkagg', 'tkcairo',
           'webagg', 'webpng', 'wx', 'wxagg', 'wxcairo'}

def entry_name_safe(name: str) -> bool:
    return name.lower() not in BUILTIN and not name.lower().startswith('module://')

BUILTIN_BACKENDS = {'agg', 'pdf', 'ps', 'svg', 'template', 'qtagg',
                     'qt5agg', 'tkagg', 'macosx', 'webagg', 'wxagg', ...}

def is_unique_backend_name(name: str) -> bool:
    return name.lower() not in BUILTIN_BACKENDS

try:
    import matplotlib.pyplot as plt
except RuntimeError as e:
    if 'built-in backend' in str(e):
        raise SystemExit('A plugin shadows a built-in backend name; '
                         'uninstall it or report upstream') from e
    raise

When it happens

Trigger: A package declares an entry point under [project.entry-points.'matplotlib.backends'] with name 'agg', 'pdf', 'qt5agg', 'webagg', etc. The error appears at backend-registry construction (typically first matplotlib import) in every environment that has the package installed.

Common situations: Plugin authors naming their backend after the core one it extends (e.g. a faster 'svg' or a themed 'agg'); fork packages that kept the original backend's name; end users suddenly unable to import matplotlib after pip installing such a package.

Related errors

• Entry point name '{name}' cannot start with 'module://'
• Matplotlib requires {modname}>={minver}; you have {module.__
• str(_cpe)
• Timed out running {cbook._pformat_subprocess(args)}
• str(_ose)

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