LibreOffice GUI Toolkit Environment Variables

This article explains how to control the graphical user interface (GUI) toolkit in LibreOffice on Linux and UNIX-like systems using environment variables. It details the primary variable, SAL_USE_VCLPLUGIN, describes the supported backend values—such as GTK, Qt/KDE, and generic X11—and outlines related environment variables that influence desktop rendering and windowing backends.

The Primary Variable: SAL_USE_VCLPLUGIN

LibreOffice relies on an abstraction layer called the Visual Class Library (VCL) to render its interface. The SAL_USE_VCLPLUGIN environment variable tells LibreOffice which specific VCL plugin (graphical toolkit backend) to load upon startup.

Supported Plugin Values

• gtk3: Uses the GTK 3 toolkit. This provides native integration for GNOME, Xfce, MATE, and other GTK-based desktop environments.
• gtk4: Uses the GTK 4 toolkit. Available in newer builds as an experimental backend.
• kf5 / qt5: Uses KDE Frameworks 5 or pure Qt 5. This enables native look and feel, file dialogs, and styling on KDE Plasma 5 desktops.
• kf6 / qt6: Uses KDE Frameworks 6 or pure Qt 6. This is targeted for modern KDE Plasma 6 environments.
• gen: The “Generic” X11 fallback plugin. It uses basic Xlib rendering without modern desktop theming. It is primarily used for debugging crashes, diagnosing font/rendering bugs, or running on minimal window managers.
• svp: Headless/Virtual plugin used primarily for automated testing without an active display server.

Usage Examples

To run LibreOffice with a specific toolkit from the command line, prepend the variable to the launch command:

# Force LibreOffice to use the GTK 3 interface
SAL_USE_VCLPLUGIN=gtk3 libreoffice

# Force LibreOffice to use the Qt 5 / KF5 interface
SAL_USE_VCLPLUGIN=kf5 libreoffice

# Force LibreOffice to run in generic fallback mode (useful for troubleshooting)
SAL_USE_VCLPLUGIN=gen libreoffice

To make the change permanent for your user session, export the variable in your shell profile (such as ~/.bashrc or ~/.profile):

export SAL_USE_VCLPLUGIN=gtk3

Supporting and Legacy Environment Variables

In addition to SAL_USE_VCLPLUGIN, several other variables influence the toolkit selection, display server integration, and rendering pipeline:

1. OOO_FORCE_DESKTOP

A legacy configuration variable from earlier versions of OpenOffice and LibreOffice. It accepts values such as gnome, kde, or none. Modern LibreOffice versions automatically map OOO_FORCE_DESKTOP to the corresponding SAL_USE_VCLPLUGIN setting, but SAL_USE_VCLPLUGIN is preferred.

2. Display Server Variables (GDK_BACKEND and QT_QPA_PLATFORM)

When using gtk3 or qt5/kf5 plugins, underlying toolkit variables control whether the application communicates via native Wayland or X11/XWayland:

• Force X11 on GTK: GDK_BACKEND=x11 SAL_USE_VCLPLUGIN=gtk3 libreoffice
• Force Wayland on Qt: QT_QPA_PLATFORM=wayland SAL_USE_VCLPLUGIN=qt5 libreoffice

3. Rendering and Scaling Variables

• SAL_FORCEDPI: Overrides the DPI value reported by the display server (e.g., SAL_FORCEDPI=96 libreoffice), useful for resolving scaling inconsistencies across toolkits.
• SAL_DISABLE_GL or SAL_ENABLE_GL: Disables or forces OpenGL hardware acceleration in the UI rendering pipeline.
• SAL_FORCE_SKIA: Controls whether LibreOffice uses the Skia rendering engine (SAL_FORCE_SKIA=raster or SAL_FORCE_SKIA=vulkan).