{"record":{"id":"f7d3317256fe7461","repo":"matplotlib/matplotlib","slug":"entry-point-name-name-is-a-built-in-backend","errorCode":null,"errorMessage":"Entry point name '{name}' is a built-in backend","messagePattern":"Entry point name '(.+?)' is a built-in backend","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"lib/matplotlib/backends/registry.py","lineNumber":178,"sourceCode":"                entries, \"ipympl\", (0, 9, 4), [\"ipympl\", \"widget\"],\n                \"ipympl.backend_nbagg\")\n\n        return entries\n\n    def _validate_and_store_entry_points(self, entries):\n        # Validate and store entry points so that they can be used via matplotlib.use()\n        # in the normal manner. Entry point names cannot be of module:// format, cannot\n        # shadow a built-in backend name, and there cannot be multiple entry points\n        # with the same name but different modules. Multiple entry points with the same\n        # name and value are permitted (it can sometimes happen outside of our control,\n        # see https://github.com/matplotlib/matplotlib/issues/28367).\n        for name, module in set(entries):\n            name = name.lower()\n            if name.startswith(\"module://\"):\n                raise RuntimeError(\n                    f\"Entry point name '{name}' cannot start with 'module://'\")\n            if name in self._BUILTIN_BACKEND_TO_GUI_FRAMEWORK:\n                raise RuntimeError(f\"Entry point name '{name}' is a built-in backend\")\n            if name in self._backend_to_gui_framework:\n                raise RuntimeError(f\"Entry point name '{name}' duplicated\")\n\n            self._name_to_module[name] = \"module://\" + module\n            # Do not yet know backend GUI framework, determine it only when necessary.\n            self._backend_to_gui_framework[name] = \"unknown\"\n\n    def backend_for_gui_framework(self, framework):\n        \"\"\"\n        Return the name of the backend corresponding to the specified GUI framework.\n\n        Parameters\n        ----------\n        framework : str\n            GUI framework such as \"qt\".\n\n        Returns\n        -------","sourceCodeStart":160,"sourceCodeEnd":196,"githubUrl":"https://github.com/matplotlib/matplotlib/blob/b379c1b69e012b142c0f496a52bcb30513802d72/lib/matplotlib/backends/registry.py#L160-L196","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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","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","Confirm the fix by importing matplotlib and calling matplotlib.use('<new-unique-name>')"],"exampleFix":"# before (pyproject.toml)\n[project.entry-points.'matplotlib.backends']\nagg = 'myplugin.faster_agg'\n\n# after\n[project.entry-points.'matplotlib.backends']\nfaster-agg = 'myplugin.faster_agg'","handlingStrategy":"validation","validationCode":"BUILTIN = {'agg', 'pdf', 'ps', 'svg', 'template', 'cairo', 'gtk3agg',\n           'gtk3cairo', 'gtk4agg', 'gtk4cairo', 'macosx', 'nbagg', 'notebook',\n           'qt5agg', 'qt5cairo', 'qtagg', 'qtcairo', 'tkagg', 'tkcairo',\n           'webagg', 'webpng', 'wx', 'wxagg', 'wxcairo'}\n\ndef entry_name_safe(name: str) -> bool:\n    return name.lower() not in BUILTIN and not name.lower().startswith('module://')","typeGuard":"BUILTIN_BACKENDS = {'agg', 'pdf', 'ps', 'svg', 'template', 'qtagg',\n                     'qt5agg', 'tkagg', 'macosx', 'webagg', 'wxagg', ...}\n\ndef is_unique_backend_name(name: str) -> bool:\n    return name.lower() not in BUILTIN_BACKENDS","tryCatchPattern":"try:\n    import matplotlib.pyplot as plt\nexcept RuntimeError as e:\n    if 'built-in backend' in str(e):\n        raise SystemExit('A plugin shadows a built-in backend name; '\n                         'uninstall it or report upstream') from e\n    raise","preventionTips":["Prefix plugin backend names with your package name (e.g. 'acme-agg')","Check matplotlib's built-in backend list before publishing a plugin","Isolate development environments so plugin packaging bugs don't break core workflows"],"tags":["matplotlib","entry-points","packaging","name-collision","backend-registration"],"backgroundTag":"invalid-plugin-entry-point","analyzedSha":"b379c1b69e012b142c0f496a52bcb30513802d72","analyzedAt":"2026-08-21T23:31:55.468Z","schemaVersion":2},"datasetVersion":"2026-08-22T04:17:13.399Z"}