Quarto uses a headless browser behind the scenes to render Mermaid and Graphviz diagrams to PNG for print formats like PDF and DOCX. Until now, this meant installing Puppeteer-bundled Chromium via quarto install chromium — a setup that worked, but came with some rough edges.
Starting with Quarto 1.9, quarto install chromium is deprecated. The recommended replacement is Chrome Headless Shell, a lightweight, headless-only browser from Google’s Chrome for Testing infrastructure.
Why the switch?
Puppeteer-bundled Chromium served Quarto well, but it had limitations that kept coming up:
- System dependencies in containers: The Puppeteer Chromium binary requires system libraries that aren’t always present in minimal Docker images or WSL environments. This led to cryptic errors that were hard to debug.
- No arm64 Linux support: Puppeteer didn’t distribute Chromium builds for arm64 Linux, leaving users on platforms like Raspberry Pi or AWS Graviton without an easy install path.
- Large download size: The full Chromium bundle is significantly larger than what Quarto actually needs for headless rendering.
Chrome Headless Shell solves all three. It’s purpose-built for headless automation, has fewer system dependencies, ships arm64 Linux builds, and is smaller to download.
Installing Chrome Headless Shell
If you don’t already have Chrome or Edge installed on your system, install Chrome Headless Shell:
Terminal
quarto install chrome-headless-shellQuarto will automatically detect and use any existing Chrome or Edge browser on your system. Chrome Headless Shell is the recommended fallback for environments where a full browser isn’t available — CI servers, Docker containers, and headless VMs.
Migrating from Chromium
If you previously installed Chromium via quarto install chromium, the migration is straightforward:
Terminal
quarto uninstall chromium
quarto install chrome-headless-shellRunning quarto check install will warn you if a legacy Chromium installation is detected and suggest the migration.
CI and automation
If your CI pipeline uses quarto install chromium --no-prompt, it will continue to work — the command still installs a working headless browser, but now shows a deprecation warning. Updating your scripts to quarto install chrome-headless-shell --no-prompt avoids the warning and uses the new tool directly. In Quarto 1.10, quarto install chromium will transparently redirect to Chrome Headless Shell, so either command will produce the same result.
What’s next
The transition away from Puppeteer Chromium is happening gradually. In Quarto 1.9, quarto install chromium shows a deprecation warning and quarto check install flags any legacy Chromium installation. In the upcoming Quarto 1.10, quarto install chromium will transparently redirect to Chrome Headless Shell, and installing Chrome Headless Shell will auto-remove any legacy Chromium.
If you’re still using the old Chromium install, now is a good time to switch.
Learn more on the Chrome Install documentation page.
The Chromium icon in the listing and social card image for this post is by Jeremiah via icon-icons.com. License: CC BY 4.0
