Configure Chrome headless shell for Document Converter

Google Chrome removed headless functionality on 8 January 2025. This may have an impact on your HTML-to-PDF and email-to-PDF conversions.

What is Chrome headless shell?

Google designed Chrome headless shell as a replacement for Chrome’s headless mode, targeting automated tasks like HTML-to-PDF conversion. This change only affects on-premises installations using Chrome for HTML or email conversions.

Who is affected?

The affected user groups are outlined below.

Cloud solutions

Cloud solution users aren’t impacted. Nutrient takes care of everything for them.

On-premises solutions

On-premises customers might have to make changes to their configuration to continue using HTML-to-PDF and email-to-PDF conversion functionality.

Am I affected?

You need to take action if all of the following apply to you:

You’re using Document Converter version 10.3.1 or newer
You’re using the Chrome application for HTML- or email-to-PDF conversion
You’re running Windows Server 2016 or newer

If you’re using version 10.3.0 or earlier, you don’t have to do anything, and this change won’t impact you.

What are my options?

If you’re affected, you have two choices:

Switch to Chrome headless shell — For Windows Server 2016+
Switch to portable Chromium (BlinkBinaries) — Works on any Windows version

Determining what you’re using

To verify if you’re using the Chrome application, examine your configuration file. Open the Muhimbi.DocumentConverter.Service.exe configuration file in a text editor — usually located in C:\Program Files\Muhimbi Document Converter — and look for the following configuration entries:

<add key="HTMLConverterFullFidelity.UseInstalledChromiumBrowser" value="Chrome"/>
<add key="HTMLConverterFullFidelity.ChromiumPath" value=""/>

If you’ve set UseInstalledChromiumBrowser to Chrome, then you’re using the Chrome application for HTML-to-PDF conversion. In this case, do one of the following:

Switch to using portable Chromium (BlinkBinaries) instead of the Chrome application. Instructions on how to use portable Chromium can be found here.
Switch to using Chrome headless shell.

Setting up Chrome headless shell

Prerequisites

Before you begin, ensure you have:

.NET Framework 4.8 or later installed
Administrator privileges on the server
Internet access for downloading Chrome headless shell
Document Converter version 10.3.1 or newer

Installation steps

Download our Chrome headless shell updater application(opens in a new tab).
Extract the Nutrient.ChromeHeadlessShellUpdater.exe application into the installation folder of the Document Converter service (usually found at C:\Program Files\Muhimbi Document Converter) and run it as an administrator.
Select option two (update Chrome headless shell package). This downloads the latest Chrome headless shell and places it in the ChromeHeadlessShell folder next to your service executable.
Change the configuration file of the conversion service to point to the newly downloaded ChromeHeadlessShell folder — usually found at C:\Program Files\Muhimbi Document Converter\ChromeHeadlessShell — like so:
```
<add key="HTMLConverterFullFidelity.UseInstalledChromiumBrowser" value=""/>
<add key="HTMLConverterFullFidelity.ChromiumPath" value="C:\Program Files\Muhimbi Document Converter\ChromeHeadlessShell\"/>
```
Restart the conversion service.

Rerun the Nutrient.ChromeHeadlessShellUpdater.exe application any time in the future to update the Chrome headless shell to the latest stable version.

Important notes

As of version 12.3.0, Nutrient.ChromeHeadlessShellUpdater.exe is part of the Document Converter product.

By default, beginning with version 12.3, Chrome headless shell serves as the default HTML-to-PDF converter and updates itself automatically whenever the service restarts. The following configuration entries influence this behavior.

<!-- It is possible to use the version of the Chrome application which is installed system-wide. This configuration only has effect if the 'HTMLConverterFullFidelity.HtmlRenderingEngine' configuration is set to "Chromium". Accepted values:
* Chrome - The software will try to detect the installed instance of Chrome and will use it for converting HTML documents into PDF.
* ChromeHeadlessShell - The system will use the Chrome Headless Shell located in the ChromeHeadlessShell folder
* Leave empty if you wish to use portable Chromium. In that case ChromiumPath must be filled.-->
<add key="HTMLConverterFullFidelity.UseInstalledChromiumBrowser" value="ChromeHeadlessShell"/>

<!-- It is possible to use a custom version of portable Chromium stored on the local file system. This only has effect if 'HTMLConverterFullFidelity.HtmlRenderingEngine' is set to 'Chromium' and 'HTMLConverterFullFidelity.UseInstalledChromiumBrowser' is left empty. Enter the full path of the folder containing the custom portable Chromium executable. -->
<add key="HTMLConverterFullFidelity.ChromiumPath" value=""/>

<!-- If set to 'true', Chrome Headless Shell stays up to date. The system downloads new versions when available during service (re)start and stores the up-to-date version in the ChromeHeadlessShell folder. -->
<add key="HTMLConverterFullFidelity.AutoUpdateChromeHeadlessShell" value="true"/>

Chrome headless shell only supports Windows Server 2016 and later. If you run an older version of Windows, you must use either the installed Chrome application or portable Chromium (aka BlinkBinaries).

Troubleshooting

Below are some common issues and their solutions.

Common installation issues

Problem — Access denied error when running the updater.

Solution — Run Nutrient.ChromeHeadlessShellUpdater.exe as an administrator.

Problem — Download fails or times out.

Solution — Check your internet connection and firewall settings. The updater needs access to Google’s Chrome download servers

Problem — Service fails to start after configuration change.

Solution — Verify ChromiumPath points to the correct folder and contains the Chrome headless shell executable.

Validation steps

After completing the configuration:

Restart the Document Converter service.
Check the service logs for any Chrome headless shell-related errors.
Test HTML-to-PDF conversion with a simple HTML page.
Monitor service performance to ensure conversion times remain acceptable.

Configuration examples

Using Chrome headless shell with automatic updates (for Windows Server 2016 and later):

<add key="HTMLConverterFullFidelity.UseInstalledChromiumBrowser" value="ChromeHeadlessShell"/>
<add key="HTMLConverterFullFidelity.ChromiumPath" value=""/>
<add key="HTMLConverterFullFidelity.AutoUpdateChromeHeadlessShell" value="true"/>

Using portable Chrome, also known as BlinkBinaries (for any Windows versions):

<add key="HTMLConverterFullFidelity.UseInstalledChromiumBrowser" value=""/>
<add key="HTMLConverterFullFidelity.ChromiumPath" value="<path to BlinkBinaries>"/>
<add key="HTMLConverterFullFidelity.AutoUpdateChromeHeadlessShell" value="false"/>

Using installed Chrome application (for Windows Server 2012 R2 and earlier):

<add key="HTMLConverterFullFidelity.UseInstalledChromiumBrowser" value="Chrome"/>
<add key="HTMLConverterFullFidelity.ChromiumPath" value=""/>
<add key="HTMLConverterFullFidelity.AutoUpdateChromeHeadlessShell" value="false"/>