Skip to main content

Chrome Headless Shellv4.0.208

From v4.0.208, Remotion will download Chrome Headless Shell before the first render.
This will future-proof your Remotion project, because headless mode will be removed in a future version of Chrome.

Supported platforms​

The following platforms are supported:

Ensure Headless Shell is available​

There are two ways to ensure Chrome Headless Shell is available:

It is recommended use call these functions if you do server-side rendering.
That way, if a request comes in wanting to render a video, the browser is already downloaded and ready to go.

Bring your own binary​

If you don't want Chrome Headless Shell to get installed or your platform is not supported, you need to specify your own Chromium-based browser:

In Lambda and Cloud Run, a version of Chrome is already installed, so you don't need to do anything.

note

In a future version of Chrome, headless mode in the desktop browser will stop being supported and you will need to use the Chrome Headless Shell.

Download location​

Chrome Headless Shell will download to

node_modules/.remotion/chrome-headless-shell/[platform]/chrome-headless-shell-[platform]
node_modules/.remotion/chrome-headless-shell/[platform]/chrome-headless-shell-[platform]

platform can be one of mac-arm64, mac-x64, linux64, linux-arm64 or win64.

At this path, a folder with the necessary files will be created.
An executable ./chrome-headless-shell (.\chrome-headless-shell.exe on Windows) will be created.

Why this change?​

Remotion previously used the desktop version of Chrome that many users had already installed.
This workflow is bound to break at some point, which is why Remotion is not picking up the desktop version of Chrome anymore.

Best practices​

To ensure your project does not get disrupted by an upcoming Chrome change, you should use the Remotion mechanisms which uses and pins the version of Chrome Headless Shell.

  • Use Remotion v4.0.208 or later to not pick up an externally installed browser.
  • Use npx remotion browser ensure to ensure Chrome Headless Shell is available.
  • Do not download Chrome in your Dockerfile, but do install Linux dependencies if you use Linux.
  • Do not use --browser-executable, browserExecutable or setBrowserExecutable() options to override the Headless Shell with an incompatible Chrome version.
warning

Note: Most Linux distros do not allow you to pin a Chrome package.
If you use a Remotion version below v4.0.208, you are at risk of Chrome automatically being upgraded to a version that does not ship with a headless mode.

What is Chrome Headless Shell?​

Chrome used to ship with a --headless flag, which Remotion would use.

As of Chrome 123, the headless mode is split up into:

  • --headless=old, which is ideal for screenshotting (and therefore Remotion)
  • --headless=new, which is ideal for browser testing

--headless=old will stop working in a future version of Chrome.
The old headless mode is being extracted into "Chrome Headless Shell".

Hence we encourage you to use Chrome Headless Shell to future-proof your Remotion application.

Version​

Remotion will download a well-tested Chrome version from the 123.0.6312 release line.
Upgrades may happen in a patch release and will be listed here.

On Lambda and Cloud Run​

If you are using Remotion Lambda or Cloud Run, you don't need to worry about installing a browser - it is included in the runtime already.

Previous changes​

Thorium (v4.0.18 - v4.0.135)​

In these versions, if no local browser can be found, an instance of Thorium is downloaded.

Thorium is a free and open-source browser forked off Chromium, which includes the codecs needed to render videos.

Chromium (before v4.0.18)​

In previous versions, Remotion would download the free version of Chromium, which would not include codecs for the proprietary H.264 and H.265 codecs. This would often lead to problems when using the <Video> tag.

See also​