{"record":{"id":"33c586fad4c2a830","repo":"docling-project/docling","slug":"playwright-is-required-for-html-rendering-install","errorCode":null,"errorMessage":"Playwright is required for HTML rendering. Install it with 'pip install \"docling[htmlrender]\"' and run 'playwright install'.","messagePattern":"Playwright is required for HTML rendering\\. Install it with 'pip install \"docling\\[htmlrender\\]\"' and run 'playwright install'\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"docling/backend/html_backend.py","lineNumber":678,"sourceCode":"        soup.head.insert(0, base_tag)\n        return str(soup)\n\n    def _pad_image(self, image: Image.Image, width: int, height: int) -> Image.Image:\n        if image.width == width and image.height == height:\n            return image\n        canvas = Image.new(\"RGB\", (width, height), color=(255, 255, 255))\n        canvas.paste(image, (0, 0))\n        return canvas\n\n    def _render_with_browser(self) -> None:\n        options = cast(HTMLBackendOptions, self.options)\n        if not options.render_page:\n            return\n\n        try:\n            from playwright.sync_api import sync_playwright  # type: ignore\n        except ImportError as exc:\n            raise RuntimeError(\n                \"Playwright is required for HTML rendering. \"\n                \"Install it with 'pip install \\\"docling[htmlrender]\\\"' and run \"\n                \"'playwright install'.\"\n            ) from exc\n\n        width, height = self._get_render_page_size()\n        self._rendered_page_size = Size(width=width, height=height)\n\n        render_url: Optional[str] = None\n        render_html = self._get_render_html_text()\n\n        if isinstance(self.path_or_stream, Path):\n            render_url = self.path_or_stream.resolve().as_uri()\n        elif self.base_path:\n            render_html = self._inject_base_tag(\n                render_html, self._coerce_base_url(self.base_path)\n            )\n","sourceCodeStart":660,"sourceCodeEnd":696,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/backend/html_backend.py#L660-L696","documentation":"_render_with_browser() raises RuntimeError when HTMLBackendOptions.render_page is enabled but playwright.sync_api cannot be imported, with the original ImportError chained. Browser-based rendering is a separate extra (htmlrender) and additionally needs browser binaries installed via `playwright install`.","triggerScenarios":"Setting HTMLBackendOptions(render_page=True) without the playwright package installed; or having the package but never running `playwright install` (that fails later at launch, not here).","commonSituations":"Enabling render_page to get visually-faithful HTML conversion in slim environments; CI images missing the extra and the browser binaries; headless servers without the chromium download cached.","solutions":["Install the extra: pip install 'docling[htmlrender]'","Run `playwright install chromium` once per environment (and `playwright install-deps` on bare Linux)","If rendering is optional, set render_page=False in constrained environments"],"exampleFix":"# before\nopts = HTMLBackendOptions(render_page=True)  # RuntimeError: Playwright required\n\n# after\n# pip install 'docling[htmlrender]' && playwright install chromium\nopts = HTMLBackendOptions(render_page=True)","handlingStrategy":"validation","validationCode":"if opts.render_page:\n    try:\n        from playwright.sync_api import sync_playwright  # noqa: F401\n    except ImportError:\n        raise RuntimeError(\"Install: pip install 'docling[htmlrender]' && playwright install\")","typeGuard":null,"tryCatchPattern":"try:\n    result = converter.convert(src)\nexcept RuntimeError as exc:\n    if 'Playwright' in str(exc):\n        opts.render_page = False  # degrade gracefully if rendering is optional\n        result = converter.convert(src)\n    else:\n        raise","preventionTips":["Install the htmlrender extra and run `playwright install` in build images","Make render_page configurable so constrained environments can disable it"],"tags":["html","playwright","rendering","optional-dependency"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}