⚙️ Configuring QtWebEngine Environment Variables

Ensure stable behavior of QtWebEngine across different systems

Overview

To ensure stable behavior of QtWebEngine across different systems, you may need to set specific environment variables. These settings improve compatibility on machines with limited GPU support or strict sandboxing rules.

Note: These settings are particularly useful if you experience crashes, blank screens, or rendering issues in the layer preview window.

Environment Variables

The following environment variables help ensure QtWebEngine runs reliably:

1. Disable QtWebEngine Sandbox

Variable: QTWEBENGINE_DISABLE_SANDBOX

Value:

1

Disables the Chromium sandbox, which can cause issues on some systems.

2. Chromium Flags for Stability

Variable: QTWEBENGINE_CHROMIUM_FLAGS

Value:

--no-sandbox --disable-gpu --disable-dev-shm-usage --disable-software-rasterizer --disable-background-timer-throttling --disable-backgrounding-occluded-windows --disable-renderer-backgrounding --disable-features=TranslateUI --single-process

These flags disable various Chromium features that can cause instability.

3. Force Software OpenGL

Variable: QT_OPENGL

Value:

software

Forces Qt to use software rendering instead of hardware acceleration.

Windows Setup

Windows

Set environment variables through System Properties:

  1. Press Win + R, type sysdm.cpl, and press Enter
  2. Go to the Advanced tab
  3. Click Environment Variables
  4. Under "User variables" or "System variables", click New
  5. Add each variable with its corresponding value:
Variable Name Value
QTWEBENGINE_DISABLE_SANDBOX 1
QTWEBENGINE_CHROMIUM_FLAGS --no-sandbox --disable-gpu --disable-dev-shm-usage --disable-software-rasterizer --disable-background-timer-throttling --disable-backgrounding-occluded-windows --disable-renderer-backgrounding --disable-features=TranslateUI --single-process
QT_OPENGL software
Note: You may need to restart QGIS (or your computer) for the changes to take effect.

Linux Setup

Linux

Add the following lines to your shell configuration file (~/.bashrc, ~/.zshrc, or /etc/environment):

export QTWEBENGINE_DISABLE_SANDBOX=1
export QTWEBENGINE_CHROMIUM_FLAGS="--no-sandbox --disable-gpu --disable-dev-shm-usage --disable-software-rasterizer --disable-background-timer-throttling --disable-backgrounding-occluded-windows --disable-renderer-backgrounding --disable-features=TranslateUI --single-process"
export QT_OPENGL=software

After adding these lines, either:

  • Run source ~/.bashrc (or your shell config file)
  • Or log out and log back in
  • Or restart your computer

macOS Setup

macOS

For Terminal Applications

Add the following lines to ~/.zshrc:

export QTWEBENGINE_DISABLE_SANDBOX=1
export QTWEBENGINE_CHROMIUM_FLAGS="--no-sandbox --disable-gpu --disable-dev-shm-usage --disable-software-rasterizer --disable-background-timer-throttling --disable-backgrounding-occluded-windows --disable-renderer-backgrounding --disable-features=TranslateUI --single-process"
export QT_OPENGL=software

For Apps Launched from Finder or Dock

If you launch QGIS from Finder or the Dock, you need to set environment variables using launchctl:

launchctl setenv QTWEBENGINE_DISABLE_SANDBOX 1
launchctl setenv QTWEBENGINE_CHROMIUM_FLAGS "--no-sandbox --disable-gpu --disable-dev-shm-usage --disable-software-rasterizer --disable-background-timer-throttling --disable-backgrounding-occluded-windows --disable-renderer-backgrounding --disable-features=TranslateUI --single-process"
launchctl setenv QT_OPENGL software
Important: The launchctl setenv commands need to be run after each system restart, or you can add them to a login script.

Next Steps

↑