Chromium tool should be used by default if installed

[jlperla]

I have:

• searched the issue tracker for similar issues
• installed the latest version of Quarto CLI
• formatted my issue following the Bug Reports guide

Bug description

I had a great deal of trouble getting some of my code working in CI due to hangs (more intermittent, but happened on my computer as well). Still not sure what markdown caused the issue (possibly graphviz).

However, the details of my issue are less important than the proposed solution: if quarto install tool chromium has been executed, then it should be the default CHROMIUM unless QUARTO_CHROMIUM has been explicitly set. The behavior right now is that you need to manually find and set that environment variable .

Steps to reproduce

What would happen is that when compiling a ipynb: default for my setup, it would sometimes hang and debugging information was not especially helpful. Eventually I tracked it down to a hanging of chromium (which was preinstalled in the container image).

Actual behavior

Intermittent hanging.

If you install the quarto install tool chromium then a quarto check defaults to the system Chromium if it can find it, rather than the newly installed tool.

Expected behavior

My workaround in CI was the following:

 quarto install tool chromium
 export QUARTO_CHROMIUM=$(find /home/runner/.local/share/quarto/chromium -type f -name chrome -print -quit)
 echo "QUARTO_CHROMIUM=$QUARTO_CHROMIUM" >> $GITHUB_ENV     

Then checked with quarto check
But that is very specific to the CI setup. On a general computer it is difficult to find where the tool was installed.

Right now the logic seems to be:

1. Quarto searches for a chromium installation (whether or not the tool is installed).
2. If it finds an installation and no QUARTO_CHROMIUM has been set, then it uses the installation it finds and ignores the toool
3. If it found a tool and QUARTO_CHROMIUM has been set, then it uses that environment variable
4. Finally, and I can only assume this because was unable to setup a machine without chromium, if it can't find a system installation then it defaults t the tool?

Proposed logic:

1. If QUARTO_CHROMIUM has been set, use it and do not even search for system or tool
2. Otherwise, if the chromium tool is installed then use it.
3. Otherwise try to find a system installation and quarto check should return an error if none of these were found.

Your environment

• Quarto 1.7 and tested on Quarto 1.8

Quarto check output

This was on multiple machines. See above.

[jlperla]

Thanks for considering this! It was a brutal process tracking this issue down. Hopefully it is easy enough to flip for quarto 1.8 if you agree with the suggestion.

[cscheid]

Unfortunately no, we're not going to consider this for 1.8. We first need to decide if and how we want to fix this at all. quarto check should needs to test the currently installed tools, so the proposed solution can't work.

[jlperla]

I understand.

In the meantime, if it won't be considered for a 1.8 release, then perhaps there is a way to provide a way to get the path of the installed tool within Quarto which is OS independent? Then one can at least find the path yourself and manually set QUARTO_CHROMIUM.

[mcanouil]

Finally, and I can only assume this because was unable to setup a machine without chromium, if it can't find a system installation then it defaults t the tool?

Yes.

1. If QUARTO_CHROMIUM has been set, use it and do not even search for system or tool
2. Otherwise, if the chromium tool is installed then use it.
3. Otherwise try to find a system installation and quarto check should return an error if none of these were found.

That's the logic for the environment variable, see below an extract of my quarto check.
To summarise, you want the tool to have precedence over a system version?
(The tool is outdated by the way)

[✓] Checking tools....................OK
      TinyTeX: v2025.08.02
      Chromium: (not installed)

[✓] Checking Chrome Headless....................OK
      Using: Chrome found on system
      Path: /Applications/Brave Browser.app/Contents/MacOS/Brave Browser
      Source: QUARTO_CHROMIUM

[jlperla]

Gotcha.

The short answer is Yes, I think that if someone went through the trouble of installing the chromium tool then it should be the default rather than the system chrome (but if they set QUARTO_CHROMIUM it should take precedence).

The tool might be outdated, but the system ones crashed on both my macOS and the GitHub CI!

[mcanouil]

Could you share a small repository setup showing this?

[jlperla]

I am so sorry but I coudlnt' get a minimal working example. It was a mess to even find that it was related to the headless chrome given how intermittent it was and the lack of debugging information (even setting --log-level debug didn't help much) . If I ever find a way to reproduce it, I will let you know.

If it happens on my machine again (the one without the tool installed) then what logfile/output would help you see why it was hanging?

[jlperla]

FWIW, it is the sort of bug where if it hangs on your desktop you just hit ctrl+c and then restart and it usually works the second time. And this only happens with the .ipynb format, so there must be something go on with generating figures specific to that.

[jlperla]

Could you reply in the same thread? It scatters your reply over all the discussion instead of stacking them in one thread to follow.

That's odd. it might be about the headless mode which changed between the outdated tool that Quarto installs and all current chromium-based browser. That's the only big difference I can think of. You can look for the discussions/issues about this.

• Chrome Headless improvements #11877

Sorry, will try to navigate the threads better.

Yes, when I was trying to solve my problem I found that issue, but it mostly seemed to be looking at issues with the quarto chromium tool which is the opposite of my problem (i.e., using the tool fixes my problem).

On my desktop, where I have seen the issue occur several times (even if not reproductible) I have:

(grad-econ-datascience) ➜  grad_econ_datascience git:(main) quarto check
Quarto 1.7.33
[✓] Checking environment information...
      Quarto cache location: /Users/jlperla/Library/Caches/quarto
[✓] Checking versions of quarto binary dependencies...
      Pandoc version 3.6.3: OK
      Dart Sass version 1.85.1: OK
      Deno version 1.46.3: OK
      Typst version 0.13.0: OK
[✓] Checking versions of quarto dependencies......OK
[✓] Checking Quarto installation......OK
      Version: 1.7.33
      Path: /Applications/quarto/bin

[✓] Checking tools....................OK
      Chromium: 869685
      TinyTeX: (not installed)

[✓] Checking LaTeX....................OK
      Using: Installation From Path
      Path: /Library/TeX/texbin
      Version: 2025

[✓] Checking Chrome Headless....................OK
      Using: Chrome found on system
      Path: /Applications/Google Chrome.app/Contents/MacOS/Google Chrome
      Source: MacOS known location

[✓] Checking basic markdown render....OK

[✓] Checking Python 3 installation....OK
      Version: 3.13.2
      Path: /Users/jlperla/GitHub/grad_econ_datascience/.venv/bin/python3
      Jupyter: 5.8.1
      Kernels: julia-1.11, python3

[✓] Checking Jupyter engine render....OK

[✓] Checking R installation...........(None)

      Unable to locate an installed version of R.
      Install R from https://cloud.r-project.org/

Is there maybe an environment variable I need to set, or a tweak in my quarto .yml files, which makes the system chrome more like the one installed in quarto tools? Should I set QUARTO_CHROMIUM_HEADLESS_MODE to something, for example?

[mcanouil]

Should I set QUARTO_CHROMIUM_HEADLESS_MODE to something, for example?

Maybe, but that's for backward compatibility.
As I said, Google changed how chromium headless mode works which impact all browsers based on it.
It would probably be better to figure out the issue with current browsers than using old ones in the long run.

[jlperla]

Makes sense. Is there any particular log file, quarto CLI argument, etc. that I can add to try to get a log when this happens on my desktop? If so, I can try to post it up to track down the problem.

[mcanouil]

The troubleshooting tips: https://quarto.org/docs/troubleshooting/index.html

The short version about headless mode: https://quarto.org/docs/download/changelog/1.6/index.html#chromium-support

Used for adaption of the --headless mode used with QUARTO_CHROMIUM binary. Set to "none" for --headless, or to "old" or "new" to pass as argument, e.g. --headless=<QUARTO_CHROMIUM_HEADLESS_MODE>. Quarto 1.6 sets "old" as default, which works from Chrome 112 to 131. Starting Quarto 1.7.13, "none" is the default as Chrome 132 removed old headless mode.

[jlperla]

OK, I managed to get it generating in my CI with --log-level debug until it hangs. To confirm, if I add the following into CI:

 quarto install tool chromium
 export QUARTO_CHROMIUM=$(find /home/runner/.local/share/quarto/chromium -type f -name chrome -print -quit)
 echo "QUARTO_CHROMIUM=$QUARTO_CHROMIUM" >> $GITHUB_ENV     

then there is no hanging. So this output is what happens when I do not set the QUARTO_CHROMIUM and it finds whatever CI has.

The full file output is:
hanging_build.txt

But the last lines in the log are:

[trace] Parsed [Div ("",["quarto-auto-generated-content"],[("style","displa at line 535
[INFO] Running filter /opt/quarto/share/filters/main.lua
[INFO] Completed filter /opt/quarto/share/filters/main.lua in 199 ms
[execProcess] Success: true, code: 0
Starting python3 kernel...[execProcess] /home/runner/work/grad_econ_datascience/grad_econ_datascience/.venv/bin/python3 /opt/quarto/share/jupyter/jupyter.py
(Notebook read from cache)
[execProcess] Success: true, code: 0
[execProcess] which google-chrome
[execProcess] Success: true, code: 0
[CHROMIUM] Found Chromium on OS known location
[CHROMIUM] Path: /usr/bin/google-chrome

I ran it with QUARTO_CHROMIUM_HEADLESS_MODE set to new and it still seemed to hang (with the same tail of the log-file).