hyprland-wiki/pages/Configuring/Environment-variables.md

weight	title
15	Environment variables

{{< callout type=info >}}

uwsm users should avoid placing environment variables in the hyprland.conf file. Instead, use ~/.config/uwsm/env for theming, xcursor, nvidia and toolkit variables, and ~/.config/uwsm/env-hyprland for HYPR* and AQ_* variables. The format is export KEY=VAL.

export XCURSOR_SIZE=24

See uwsm readme for additional information.

{{< /callout >}}

You can use the env keyword to set environment variables prior to the initialization of the Display Server, e.g.:

env = GTK_THEME,Nord

{{< callout >}}

Hyprland puts the raw string to the envvar with the env keyword. You should not add quotes around the values.

e.g.:

env = QT_QPA_PLATFORM,wayland

and NOT

env = QT_QPA_PLATFORM,"wayland"

{{< /callout >}}

Please avoid putting those environment variables in /etc/environment. That will cause all sessions (including Xorg ones) to pick up your wayland-specific environment on traditional Linux distros.

Hyprland Environment Variables

• HYPRLAND_TRACE=1 - Enables more verbose logging.
• HYPRLAND_NO_RT=1 - Disables realtime priority setting by Hyprland.
• HYPRLAND_NO_SD_NOTIFY=1 - If systemd, disables the sd_notify calls.
• HYPRLAND_NO_SD_VARS=1 - Disables management of variables in systemd and dbus activation environments.
• HYPRLAND_CONFIG - Specifies where you want your Hyprland configuration.

Aquamarine Environment Variables

• AQ_TRACE=1 - Enables more verbose logging.
• AQ_DRM_DEVICES= - Set an explicit list of DRM devices (GPUs) to use. It's a colon-separated list of paths, with the first being the primary. E.g. /dev/dri/card1:/dev/dri/card0
• AQ_MGPU_NO_EXPLICIT=1 - Disables explicit syncing on mgpu buffers
• AQ_NO_MODIFIERS=1 - Disables modifiers for DRM buffers

Toolkit Backend Variables

• env = GDK_BACKEND,wayland,x11,* - GTK: Use wayland if available. If not: try x11, then any other GDK backend.
• env = QT_QPA_PLATFORM,wayland;xcb - Qt: Use wayland if available, fall back to x11 if not.
• env = SDL_VIDEODRIVER,wayland - Run SDL2 applications on Wayland. Remove or set to x11 if games that provide older versions of SDL cause compatibility issues
• env = CLUTTER_BACKEND,wayland - Clutter package already has wayland enabled, this variable will force Clutter applications to try and use the Wayland backend

XDG Specifications

• env = XDG_CURRENT_DESKTOP,Hyprland
• env = XDG_SESSION_TYPE,wayland
• env = XDG_SESSION_DESKTOP,Hyprland

XDG specific environment variables are often detected through portals and applications that may set those for you, however it is not a bad idea to set them explicitly.

If your desktop portal is malfunctioning for seemingly no reason (no errors), it's likely your XDG env isn't set correctly.

{{< callout type=info >}}

uwsm users don't need to explicitly set XDG environment variables, as uwsm sets them, automatically.

{{< /callout >}}

Qt Variables

• env = QT_AUTO_SCREEN_SCALE_FACTOR,1 - (From the Qt documentation) enables automatic scaling, based on the monitor's pixel density
• env = QT_QPA_PLATFORM,wayland;xcb - Tell Qt applications to use the Wayland backend, and fall back to x11 if Wayland is unavailable
• env = QT_WAYLAND_DISABLE_WINDOWDECORATION,1 - Disables window decorations on Qt applications
• env = QT_QPA_PLATFORMTHEME,qt5ct - Tells Qt based applications to pick your theme from qt5ct, use with Kvantum.

NVIDIA Specific

To force GBM as a backend, set the following environment variables:

• env = GBM_BACKEND,nvidia-drm
• env = __GLX_VENDOR_LIBRARY_NAME,nvidia

See Archwiki Wayland Page for more details on those variables.

• env = LIBVA_DRIVER_NAME,nvidia - Hardware acceleration on NVIDIA GPUs

See Archwiki Hardware Acceleration Page for details and necessary values before setting this variable.

• __GL_GSYNC_ALLOWED - Controls if G-Sync capable monitors should use Variable Refresh Rate (VRR)

See Nvidia Documentation for details.

• __GL_VRR_ALLOWED - Controls if Adaptive Sync should be used. Recommended to set as "0" to avoid having problems on some games.

• env = AQ_NO_ATOMIC,1 - use legacy DRM interface instead of atomic mode setting. NOT recommended.

Theming Related Variables

• GTK_THEME - Set a GTK theme manually, for those who want to avoid appearance tools such as lxappearance or nwg-look
• XCURSOR_THEME - Set your cursor theme. The theme needs to be installed and readable by your user.
• XCURSOR_SIZE - Set cursor size. See here for why you might want this variable set.