Development/Environment variables

    From The Document Foundation Wiki

    This page is aimed to reference and document all the environment variables that are used in LibreOffice.

    How to use environment variables

    The exact syntax depends on the shell and the OS.

    For Linux/bash, you can use SAL_USE_VCLPLUGIN variable to use gen UI using export command:

    export SAL_USE_VCLPLUGIN=gen
    instdir/program/soffice

    Another approach would be using it in the same command for running soffice:

    SAL_USE_VCLPLUGIN=gen instdir/program/soffice

    Another way would be passing the environment variable using -env, but it only works for bootstrap variables. You should note that not every variable is a bootstrap variable.

    instdir/program/soffice -env:SAL_USE_VCLPLUGIN=gen

    For Windows, one should use set in order to set the environment variable. For example, to get an RTL UI, one should use SAL_RTL_ENABLED in this way:

    SET SAL_RTL_ENABLED=1
    path-to/soffice.exe

    In PowerShell, this can be done by using a subshell to avoid permanently adding the variables:

    pwsh -Command { $env:SAL_RTL_ENABLED=1; path-to/soffice.exe }

    For one-liner in Windows to use as a shortcut, one could use set in a different way. For example, to run LO without SKIA in case of a problem and to additionally avoid restore:

    C:\Windows\System32\cmd.exe /c "set SAL_DISABLESKIA=1 && START /D ^"C:\Program Files\LibreOffice\program^" soffice.exe  --norestore"

    Another way would be passing the environment variable using -env (only bootstrap variables).

    instdir/program/soffice -env:SAL_USE_VCLPLUGIN=gen

    List of environment variables

    Note pin.svg

    Note:
    If you want to add a new environment variable to the LibreOffice source code, please note that:

    1. An environment variable is not the best way to handle the system configuration. Think about other ways of handling the system configuration that may be more appropriate.
    2. Please consider adding a prefix (like SAL_) to avoid conflicts with other environment variables from other applications.

    VCL

    General

    Variable Description
    SAL_USE_VCLPLUGIN Which VCL plugin to use instead of the auto-detected one. Possible values:

    gen: X11 UI
    qt5: Qt 5 UI
    qt6: Qt 6 UI
    kf5: KDE KF5 UI
    kf6: KDE KF6 UI
    gtk3: GTK 3 UI
    gtk4: GTK 4 UI
    gtk3_kde5: GTK 3 KDE 5 UI
    win: Windows UI (Windows only)
    osx: macOS X UI (macOS only)

    A list of these VCL plugins can be extracted by:
    grep vclplug Repository.mk in core.

    SAL_RTL_ENABLED Enable right to left (RTL) UI, used for Arabic, Persian, Hebrew and other RTL languages.
    SAL_NO_NWF Disable native widgets
    SAL_FORCEDPI Force a specific DPI (gen, gtk3/gtk4, qt5/qt6/kf5/kf6 plugins only)
    SAL_FORCE_HC force high-contrast mode
    SAL_USE_SYSTEM_LOOP Calls std::abort on nested event loop calls. Currently just for Qt with many crashes. WIP.
    SAL_NO_FONT_LOOKUP Disable font search and fallback and always use a hard-coded font name (for some unit tests)
    SAL_DISABLE_WATCHDOG don't start the thread that watches for broken GL/Vulkan/OpenCL drivers
    SAL_NO_MOUSEGRABS for debugging - stop blocking UI if a breakpoint is hit
    LO_COLLECT_UIINFO Enable the uitesting logging, value is expected to be a relative file name that will be used to write the log under instdir/uitest/.
    VCL_DOUBLEBUFFERING_AVOID_PAINT Don't paint the buffer, useful to see where we do direct painting
    VCL_DOUBLEBUFFERING_FORCE_ENABLE Enable double buffered painting
    VCL_DOUBLEBUFFERING_ENABLE Enable a safe subset of double buffered painting (currently in Writer, not in any other applications)
    VCL_DEBUG_DISABLE_PDFCOMPRESSION Disable compression in the PDF writer

    GTK

    Variable Description
    VCL_GTK3_PAINTDEBUG in debug builds, if set to 1 then holding down shift+0 forces a redraw event, shift+1 repaints everything, and shift+2 dumps cairo frames to pngs as /tmp/frame<n>.png
    GDK_SCALE=2 for X11-specific HiDPI scaling (just supports integers) [1]

    Bitmap

    Variable Description
    VCL_NO_THREAD_SCALE disable threaded bitmap scale
    VCL_NO_THREAD_IMPORT disable threaded bitmap import
    EMF_PLUS_DISABLE use EMF rendering and ignore EMF+ specifics
    EMF_PLUS_LIMIT EMF+ records limit

    OpenGL

    Variable Description
    SAL_DISABLEGL disable OpenGL use
    SAL_GL_NO_SWAP disable buffer swapping if set (should show nothing)
    SAL_GL_SLEEP_ON_SWAP sleep for half a second on each swap-buffers.

    Skia

    Variable Description
    SAL_DISABLESKIA=1 force disabled Skia
    SAL_ENABLESKIA=1 enable Skia, unless denylisted (and if the VCL backend supports Skia)
    SAL_FORCESKIA=1 force using Skia, even if denylisted
    SAL_SKIA=raster|vulkan|metal select Skia's drawing method, by default Vulkan or Metal are used if available
    SAL_DISABLE_SKIA_CACHE=1 disable caching of complex images
    SAL_SKIA_KEEP_BITMAP_BUFFER=1 SkiaSalBitmap will keep its bitmap buffer even after storing in SkImage

    OpenGL,Skia

    Variable Description
    SAL_WITHOUT_WIDGET_CACHE disable LRU caching of native widget textures

    Qt

    Variable Description
    QT_SCALE_FACTOR=2 for HiDPI testing (also supports float)
    SAL_VCL_QT_NO_FONTCONFIG (from LO 24.8 on)
    SAL_VCL_QT5_NO_FONTCONFIG (until LO 24.2)
    ignore fontconfig provided font substitutions
    SAL_VCL_QT_NO_NATIVE (from LO 24.8 on)
    SAL_VCL_QT5_NO_NATIVE (until LO 24.2)
    disable QStyle'd controls
    SAL_VCL_QT_USE_QFONT use QFont for text layout and rendering (default is to use cairo)

    Mac

    Variable Description
    SAL_FORCE_HIDPI_SCALING set to 2 to fake HiDPI drawing (useful for unit tests, windows may draw only top-left 1/4 of the content scaled)

    Dark mode

    Variable Description
    VCL_ICONS_FOR_DARK_THEME Use dark theme for LibreOffice icons
    VCL_MACOS_FORCE_DARK_MODE Enables dark mode for macOS (the implementation is incomplete)
    VCL_MACOS_USE_SYSTEM_APPEARANCE Use system settings (light mode or the dark mode as configured within system preferences)

    Direct2D

    Variable Description
    TEST_SYSTEM_PRIMITIVE_RENDERER Setting to true makes Direct2D rendering enabled. See LibreOffice graphics subsystems - SystemSpecificRenderers

    Others

    Variable Description
    LIBO_VCL_DEMO Used internally by vcldemo to differentiate the execution with the normal VCL main application as it does not use the complex configurations for icon themes and cursor images
    VCL_DRAW_WIDGETS_FROM_FILE
    VCL_DUMP_BMP_PATH
    VCL_EVENT_INJECTION

    test

    Variable Description
    LO_TEST_LOCALE the locale to be used during unit tests. Defaults to en-US.

    desktop

    General

    Variable Description
    DISPLAY X11 display to use.
    OOO_DISABLE_RECOVERY Disables the recovery dialog.
    OOO_EXIT_POST_STARTUP Exit right after startup, for profiling purposes.
    SAL_DISABLE_USERMIGRATION Disable automatic conversion of old user configurations.

    LibreOfficeKit

    Variable Description
    LOK_DEBUG Draw a small red rectangle in the top left corner so that it's easy to see where a new tile begins.
    LOK_ALLOWLIST_LANGUAGES Set the Allowlisted languages
    LOK_DEBUG_TILES Draw a small red rectangle in the top left corner so that it's easy to see where a new tile begins
    SAL_LOK_OPTIONS ':' delimited options - avoiding ABI change for new parameters. Parameters can be: unipoll, profile_events, sc_no_grid_bg, sc_print_twips_msgs, notebookbar

    oox

    ppt

    Variable Description
    OOX_NO_SMARTART_WARNING don't warn on SmartArts missing their DrawingML fallback

    sax

    fastparser

    Variable Description
    SAX_DISABLE_THREADS don't thread sax parsing

    Language Variables

    Variable Description
    ALL_LANGS
    LANG
    LANGUAGE
    LC_ALL
    LC_CTYPE
    LC_MESSAGES

    System Variables

    Variable Description
    HOME Home folder for the current user
    JAVA_HOME Path to JDK folder
    OS
    PATH List of directories to search for the executable files. This is used on Unix/Linux, Windows, macOS and many other platforms with slight difference that Windows uses ; instead of : to separate directories.
    PYTHONPATH List of directories to be added to Python sys.path
    SHELL
    TMP
    TMPDIR
    WAYLAND_DISPLAY "This tells Wayland clients which Wayland compositor to connect to. If it is not set, clients will try wayland-0 as a fallback. WAYLAND_DISPLAY is normally the name of a socket in XDG_RUNTIME_DIR, but it can also be an absolute path to a socket anywhere."
    Environment variables for Wayland hackers
    DESKTOP_LAUNCH
    DESKTOP_SESSION
    DISABLE_REDLINE
    GNOME_DESKTOP_SESSION_ID
    KDE_FULL_SESSION
    KDE_SESSION_VERSION
    SESSION_MANAGER
    TEMP
    TEST_LIB
    XDG_CACHE_HOME [2]
    XDG_CONFIG_HOME [3]
    XDG_CURRENT_DESKTOP [4]
    XMODIFIERS

    Compile/build Variables

    Variable Description
    CLANG_FORMAT
    CLANG_THRESHOLD
    CLASSPATH
    CXX
    DYLD_LIBRARY_PATH
    ENABLE_RELEASE_BUILD
    INCLUDE
    INSTDIR
    LIBO_LD_PATH
    MSVC_USE_DEBUG_RUNTIME
    MSVC_USE_INDIVIDUAL_PDBS
    SRCDIR
    SRC_ROOT
    WORKDIR
    WORKDIR_FOR_BUILD

    Debug Variables

    Variable Description
    CRASH_DUMP_ENABLE
    CPPCANVAS_DEBUG_EMFPLUS_DUMP_TO
    DBG_LWPIMPORT_DIR
    DBG_PDFIMPORT_DIR
    HELP_DEBUG
    SAL_DEBUG_UPDATES
    SAL_LOG
    SAL_LOG_FILE
    SD_DEBUG
    SAL_LOG_SYSLOG
    SW_DEBUG
    SW_DEBUG_HTML_PASTE_TO
    SW_DEBUG_MAILMERGE_DOCS
    SW_DEBUG_RTF_PASTE_FROM
    SW_DEBUG_RTF_PASTE_TO
    SW_DEBUG_WRITERFILTER

    LibreOffice Updater

    Variable Description
    LIBO_UPDATER_BUILD
    LIBO_UPDATER_CHANNEL
    LIBO_UPDATER_TEST_ENABLE
    LIBO_UPDATER_TEST_REPLACE
    LIBO_UPDATER_TEST_RUNNING
    LIBO_UPDATER_TEST_UPDATE
    LIBO_UPDATER_TEST_UPDATE_CHECK
    LIBO_UPDATER_URL

    UNO/URE Variables

    Variable Description
    UNODISABLELIBRARY
    UNO_ENV_LOG
    UNO_PATH
    URE_TEST_SETTHREADNAME

    Other Variables

    Variable Description
    AVOID_BURN_IN_FOR_GALLERY_THEME
    CANVAS_SPRITE_BOUNDS
    CONNECTIVITY_TEST_MYSQL_DRIVER_JDBC
    CPPUNIT_TEST_NAME
    FUZZ_MAX_INPUT_LEN
    GALLERY_ENABLE_ID_DIALOG
    GALLERY_SHOW_HIDDEN_THEMES
    ISC_PASSWORD
    ISC_USER
    LIBO_FLATPAK
    LIBO_FORMULA_LOG_FILE
    LIBO_ONEWAY_STABLE_ODF_EXPORT
    LIBREOFFICE_FIREBIRD_LIB
    LIBREOFFICE_ICU_LIB
    LO_IMPORT_USE_PDFIUM
    LO_LEAN_EXCEPTION
    LO_TEST_LOCALE
    LO_TESTNAME
    MAX_CONCURRENCY
    MOZILLA_CERTIFICATE_FOLDER This is deprecated
    OOO_ENABLE_LOCALE_DATA_CHECKS
    OOO_FORCE_DESKTOP
    OOO_INSTALL_PREFIX
    PDFIMPORT_RESOLUTION_DPI
    RESOURCE_NAME
    SAL_ACCESSIBILITY_ENABLED
    SAL_ANTIALIASED_TEXT_PRIORITY
    SAL_CONFIG_WINREG_RETAIN_TMP
    SAL_CUPS_PPD_RETAIN_TMP
    SAL_DECIMALSEP_ENABLED
    SAL_DISABLE_CAIRO_DOWNSCALE
    SAL_DISABLE_CPD
    SAL_DISABLE_CUPS
    SAL_DISABLE_DEFAULTPRINTER
    SAL_DISABLE_FLOATGRAB
    SAL_DISABLE_MM02_GOODIES
    SAL_DISABLE_OPENCL
    SAL_DISABLE_OWN_IM_STATUS
    SAL_DISABLE_PRINTERLIST
    SAL_DISABLE_RENDER_POLY
    SAL_DISABLE_STACKING_CHECK
    SAL_DISABLE_SYNCHRONOUS_PRINTER_DETECTION
    SAL_DISABLE_USE_CAIRO_FOR_FATLINES
    SAL_EMBEDDED_BITMAP_PRIORITY
    SAL_ENABLE_FILE_LOCKING
    SAL_ENABLE_TIMER_BITMAPDRAW
    SAL_ENABLE_USE_CAIRO_FOR_POLYGONS
    SAL_FORCEGL
    SAL_FORCE_IACCESSIBLE2 Debugging / Playing with winaccessibility: If NVDA is running when soffice starts, IA2 should be automatically enabled and work as expected. In order to use 'accprobe' to debug it is necessary to override the check for whether an AT (like NVDA) is running; to do that use: SAL_FORCE_IACCESSIBLE2=1 soffice -writer
    SAL_HIGHPRIORITY_REPAINT
    SAL_IGNOREXERRORS
    SAL_NOLOCK_PROFILE
    SAL_NO_QUERYSAVE intended for use by QA to suppress the warning on changed documents; any value is accepted even SAL_NO_QUERYSAVE="false" blocks the dialog! (tdf#143578)
    SAL_NO_XINITTHREADS
    SAL_PPDPARSER_LOCALE
    SAL_RAND_REPEATABLE
    SAL_SWITCH_OFF_ANTIALIASING_FOR_HOR_VER_BORTDERLINES
    SAL_SYNCHRONIZE
    SAL_TRANSPARENT_FLOATS
    SAL_USEINPUTMETHOD
    SAL_VISUAL
    SAL_WHEELLINES
    SAL_XKEYBOARDGROUP
    SC_FLOAT
    SC_FORCE_CALCULATION
    SC_MAX_GROUP_LENGTH
    SC_MAX_MATRIX_ELEMENTS
    SC_NO_THREADED_CALCULATION
    SC_OPENCL_DEVICE_OVERRIDE
    SD_SHOW_NUMBERING_PAGE
    SFX_MEDIUM_REUSE_STREAM
    SOFFICE_BIN
    STAR_PROFILE_LOCKING_DISABLED
    STOC_FORCE_NO_JRE
    STOC_FORCE_SYSTEM_LAF
    SVP_LISTENER_PORT
    SVX_DRAW_HANDLES
    SYSTEM_BOOST
    TAGLOGGERTMP
    TDOC
    TestUserDir
    TRACE_EVENT_RECORDING

    Commands

    In order to retrieve the list of environment variables, use the following command on the core folder (point and dollar sign because there are such vars):

    git grep -h -I 'getenv\s*(\s*"[A-Z0-9_]\+' | sed 's/.*"\([A-Za-z0-9_$.]\+\)".*/\1/g' | sort -u

    When we get the list of environment variables, we want also to see where they are used. Here is the command that searches for files that use an environment variable:

    git grep -I -H '"\s*ENV_VAR_NAME\s*"'

    See Also