{"record":{"id":"c6cef41cbb3fb86d","repo":"huggingface/tokenizers","slug":"we-couldn-t-import-ipython-utils-for-html-display","errorCode":null,"errorMessage":"We couldn't import IPython utils for html display.\nAre you running in a notebook?\nYou can also pass `default_to_notebook=False` to get back raw HTML.\n","messagePattern":"We couldn't import IPython utils for html display\\.\nAre you running in a notebook\\?\nYou can also pass `default_to_notebook=False` to get back raw HTML\\.\n","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"bindings/python/py_src/tokenizers/tools/visualizer.py","lineNumber":104,"sourceCode":"    def __init__(\n        self,\n        tokenizer: Tokenizer,\n        default_to_notebook: bool = True,\n        annotation_converter: Optional[Callable[[Any], Annotation]] = None,\n    ):\n        if default_to_notebook:\n            try:\n                from IPython.display import HTML, display  # type: ignore[attr-defined]\n            except ImportError:\n                try:\n                    from IPython.core.display import HTML, display  # type: ignore[attr-defined]\n                except ImportError:\n                    msg = (\n                        \"We couldn't import IPython utils for html display.\\n\"\n                        \"Are you running in a notebook?\\n\"\n                        \"You can also pass `default_to_notebook=False` to get back raw HTML.\\n\"\n                    )\n                    raise ImportError(msg) from None\n        self.tokenizer = tokenizer\n        self.default_to_notebook = default_to_notebook\n        self.annotation_coverter = annotation_converter\n        pass\n\n    def __call__(\n        self,\n        text: str,\n        annotations: Optional[List[Any]] = None,\n        default_to_notebook: Optional[bool] = None,\n    ) -> Optional[str]:\n        \"\"\"\n        Build a visualization of the given text\n\n        Args:\n            text (:obj:`str`):\n                The text to tokenize\n","sourceCodeStart":86,"sourceCodeEnd":122,"githubUrl":"https://github.com/huggingface/tokenizers/blob/6cfd9d385ca0ed91c10b49f0ce97d02cfde1b607/bindings/python/py_src/tokenizers/tools/visualizer.py#L86-L122","documentation":"EncodingVisualizer.__init__ lazily imports IPython's display utilities so it can render tokenizations as HTML in notebooks. When IPython (or its nbformat sub-dependency) is not installed and default_to_notebook was not explicitly set to False, the ImportError is re-raised with this explanatory message.","triggerScenarios":"Constructing `EncodingVisualizer(tokenizer)` (default default_to_notebook=True) in an environment where `from IPython.display import HTML, display` or nbformat import fails — typically IPython is not installed.","commonSituations":"Using the visualizer in a plain script, production service, or bare virtualenv without IPython; slim Docker images that omit notebook tooling; relying on the visualizer outside Jupyter without disabling notebook mode.","solutions":["Install IPython: pip install ipython (nbformat is pulled in with tokenizers' extras or install it too).","Pass `default_to_notebook=False` to EncodingVisualizer so it returns raw HTML instead of importing IPython.","If you only need the HTML string, call `to_html()`/inspect output after constructing with default_to_notebook=False."],"exampleFix":"// before\nviz = EncodingVisualizer(tokenizer)  # ImportError outside notebooks\n// after\nviz = EncodingVisualizer(tokenizer, default_to_notebook=False)\nhtml = viz.to_html(text)  # raw HTML string, no IPython needed\n// or: pip install ipython","handlingStrategy":"fallback","validationCode":"try:\n    import IPython.display  # noqa: F401\n    HAS_IPYTHON = True\nexcept ImportError:\n    HAS_IPYTHON = False\n\nviz_kwargs = {} if HAS_IPYTHON else {\"default_to_notebook\": False}\nviz = EncodingVisualizer(tokenizer, **viz_kwargs)","typeGuard":"def ipython_available() -> bool:\n    try:\n        import IPython.display\n        return True\n    except ImportError:\n        return False","tryCatchPattern":"try:\n    viz = EncodingVisualizer(tokenizer)\nexcept ImportError:\n    viz = EncodingVisualizer(tokenizer, default_to_notebook=False)","preventionTips":["Install ipython whenever tokenizations are visualized, even outside notebooks.","Pass default_to_notebook=False in scripts, CI, and services.","Probe for IPython availability before constructing the visualizer."],"tags":["python","import-error","ipython","optional-dependency","visualization"],"backgroundTag":"missing-optional-dependency","analyzedSha":"6cfd9d385ca0ed91c10b49f0ce97d02cfde1b607","analyzedAt":"2026-09-09T11:43:25.027Z","contentChangedAt":"2026-09-09T11:43:25.027Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}