docling-project/docling · error · RuntimeError

Playwright is required for HTML rendering. Install it with '

Error message

Playwright is required for HTML rendering. Install it with 'pip install "docling[htmlrender]"' and run 'playwright install'.

What it means

_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`.

Source

Thrown at docling/backend/html_backend.py:678

        soup.head.insert(0, base_tag)
        return str(soup)

    def _pad_image(self, image: Image.Image, width: int, height: int) -> Image.Image:
        if image.width == width and image.height == height:
            return image
        canvas = Image.new("RGB", (width, height), color=(255, 255, 255))
        canvas.paste(image, (0, 0))
        return canvas

    def _render_with_browser(self) -> None:
        options = cast(HTMLBackendOptions, self.options)
        if not options.render_page:
            return

        try:
            from playwright.sync_api import sync_playwright  # type: ignore
        except ImportError as exc:
            raise RuntimeError(
                "Playwright is required for HTML rendering. "
                "Install it with 'pip install \"docling[htmlrender]\"' and run "
                "'playwright install'."
            ) from exc

        width, height = self._get_render_page_size()
        self._rendered_page_size = Size(width=width, height=height)

        render_url: Optional[str] = None
        render_html = self._get_render_html_text()

        if isinstance(self.path_or_stream, Path):
            render_url = self.path_or_stream.resolve().as_uri()
        elif self.base_path:
            render_html = self._inject_base_tag(
                render_html, self._coerce_base_url(self.base_path)
            )

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Install the extra: pip install 'docling[htmlrender]'
2. Run `playwright install chromium` once per environment (and `playwright install-deps` on bare Linux)
3. If rendering is optional, set render_page=False in constrained environments

Example fix

# before
opts = HTMLBackendOptions(render_page=True)  # RuntimeError: Playwright required

# after
# pip install 'docling[htmlrender]' && playwright install chromium
opts = HTMLBackendOptions(render_page=True)

if opts.render_page:
    try:
        from playwright.sync_api import sync_playwright  # noqa: F401
    except ImportError:
        raise RuntimeError("Install: pip install 'docling[htmlrender]' && playwright install")

try:
    result = converter.convert(src)
except RuntimeError as exc:
    if 'Playwright' in str(exc):
        opts.render_page = False  # degrade gracefully if rendering is optional
        result = converter.convert(src)
    else:
        raise

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• The 'beautifulsoup4' package is required to process HTML fil
• The 'mail-parser' package is required to process email files
• The 'python-oxmsg' package is required to process Outlook .m
• Could not initialize HTML backend for file with hash {self.d
• Invalid HTML document.

AI-assisted analysis of docling-project/docling@61d76f1ff3 (2026-08-14). Data as JSON: /api/errors/33c586fad4c2a830. Report an issue: GitHub.