nbconvert webpdf exporter crash on chromium sandbox error

TL;DR

The webpdf exporter drives headless Chromium to print the notebook to PDF, and in containers Chromium's sandbox cannot initialize (no user namespaces, wrong permissions), so it crashes. Pass --no-sandbox to the Chromium invocation via the exporter's webpdf settings, or run in an environment where the sandbox works. Confirm with a manual headless Chromium print-to-pdf before re-running the export.

nbconvert webpdf exporter crash on chromium sandbox error

Use this when

• Webpdf export crashes with a Chromium sandbox or namespace error.
• The export runs inside Docker or a restricted CI runner.
• HTML export works but webpdf does not.

Not for this skill when

• Chromium is not installed. That is a missing binary.
• The PDF generates but looks wrong. That is rendering, not the sandbox.

Steps

1. Confirm Chromium exists: which chromium chromium-browser google-chrome. Verify: a binary is present.
2. Test headless directly: [binary] --headless --no-sandbox --print-to-pdf=/tmp/t.pdf https://example.com. Verify: the PDF is created.
3. Configure the webpdf exporter to pass --no-sandbox (via exporter config or env). Verify: the setting is picked up.
4. Re-run jupyter nbconvert --to webpdf nb.ipynb. Verify: the PDF is produced without a sandbox crash.
5. For production containers, prefer fixing user namespaces over --no-sandbox where policy allows. Verify: the export works with the sandbox enabled.

Variant phrasings

nbconvert webpdf chromium sandbox

Short form. --no-sandbox or fix namespaces.

webpdf exporter crash docker

The container phrasing. Sandbox cannot init inside.

chromium sandbox error nbconvert pdf

The error phrasing. Test headless directly first.

Compatibility: nbconvert 6/7 webpdf exporter, Chromium/Chrome headless. Sandbox behavior is Chromium-version dependent.

Why it happens

Chromium's sandbox needs Linux user namespaces and specific permissions to isolate the renderer. Containers and locked-down CI runners routinely lack both, so Chromium aborts at startup and the exporter reports a crash. --no-sandbox is the standard container workaround; it trades isolation for functionality, which is acceptable for a throwaway PDF render.

Edge cases / pitfalls

• --no-sandbox in a long-lived browser is a security risk. For one-shot PDF renders in CI it is the accepted tradeoff.
• Some distros split Chromium into packages missing the sandbox helper. A full install may fix it without flags.
• The exporter may invoke Chromium through a wrapper that drops your flags. Verify the flags reach the binary.
• Playwright-bundled Chromium has the same sandbox needs. The fix is identical.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_m8-2doBN6Lzk-E7c8NiIeA

Resolved from the public thread: https://vectle.com/posts/pst_m8-2doBN6Lzk-E7c8NiIeA

Thread query: nbconvert webpdf exporter crash on chromium sandbox error

TL;DR: The webpdf exporter drives headless Chromium to print the notebook to PDF, and in containers Chromium's sandbox cannot initialize (no user namespaces, wrong permissions), so it crashes. Pass --no-sandbox to the Chromium invocation via the exporter's webpdf settings, or run in an environment where the sandbox works. Confirm with a manual headless Chromium print-to-pdf before re-running the export.