From e0ea9da1f78890ead3233cc26e6f5fd3ffc91517 Mon Sep 17 00:00:00 2001 From: Marco Bulgarelli Date: Mon, 28 Jul 2025 10:35:36 +0200 Subject: [PATCH] Configuring/Environment-variables: Add usage examples (#1178) - Add warning type to callout about avoiding quotes (also reword warning). - Add examples of variable with multiple values and different formats/value separators. - Minor punctuation fixes. Note: py syntax highlighting was used for the code blocks instead of ini to avoid visualizing ";xcb" as a comment. --- content/Configuring/Environment-variables.md | 59 ++++++++++++-------- 1 file changed, 37 insertions(+), 22 deletions(-) diff --git a/content/Configuring/Environment-variables.md b/content/Configuring/Environment-variables.md index 880776f1..001ab5ee 100644 --- a/content/Configuring/Environment-variables.md +++ b/content/Configuring/Environment-variables.md @@ -5,7 +5,9 @@ title: Environment variables {{< callout type=info >}} -[uwsm](../../Useful-Utilities/Systemd-start) 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`. +[uwsm](../../Useful-Utilities/Systemd-start) 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`. ```plain export XCURSOR_SIZE=24 @@ -22,29 +24,42 @@ initialization of the Display Server, e.g.: env = GTK_THEME,Nord ``` -{{< callout >}} +{{< callout type=warning >}} -Hyprland puts the raw string to the envvar with the `env` keyword. You should -_not_ add quotes around the values. +Note that when using the `env` keyword, Hyprland reads the value of the variable as a **raw string** and puts it into the environment _as is_. +You should **NOT** add quotes `""` around the values. -e.g.: +Some examples with differently formatted values: -```ini -env = QT_QPA_PLATFORM,wayland +✗ DON'T: + +```py +env = QT_AUTO_SCREEN_SCALE_FACTOR,"1" +env = QT_QPA_PLATFORM,"wayland" +env = QT_QPA_PLATFORM,"wayland;xcb" +env = AQ_DRM_DEVICES=,"/dev/dri/card1:/dev/dri/card0" ``` -and _**NOT**_ +✓ Instead, DO: -```ini -env = QT_QPA_PLATFORM,"wayland" +```py +env = QT_AUTO_SCREEN_SCALE_FACTOR,1 +env = QT_QPA_PLATFORM,wayland +env = QT_QPA_PLATFORM,wayland;xcb +env = AQ_DRM_DEVICES=,/dev/dri/card1:/dev/dri/card0 ``` {{< /callout >}} -Please avoid putting those environment variables in /etc/environment. That will -cause all sessions (including Xorg ones) to pick up your wayland-specific + +{{< callout type=warning >}} + +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. +{{< /callout >}} + ## Hyprland Environment Variables - `HYPRLAND_TRACE=1` - Enables more verbose logging. @@ -57,19 +72,19 @@ environment on traditional Linux distros. - `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` + E.g.: `/dev/dri/card1:/dev/dri/card0` - `AQ_FORCE_LINEAR_BLIT=0` - Disables forcing linear explicit modifiers on Multi-GPU buffers to potentially workaround Nvidia issues. -- `AQ_MGPU_NO_EXPLICIT=1` - Disables explicit syncing on mgpu buffers -- `AQ_NO_MODIFIERS=1` - Disables modifiers for DRM buffers +- `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 = GDK_BACKEND,wayland,x11,*` - GTK: Use Wayland if available; if not, try X11 and 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 +- `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 @@ -87,7 +102,7 @@ no reason (no errors), it's likely your XDG env isn't set correctly. {{< callout type=info >}} - [uwsm](../../Useful-Utilities/Systemd-start) users don't need to explicitly set XDG environment variables, as uwsm sets them, automatically. + [uwsm](../../Useful-Utilities/Systemd-start) users don't need to explicitly set XDG environment variables, as uwsm sets them automatically. {{< /callout >}} @@ -97,7 +112,7 @@ no reason (no errors), it's likely your XDG env isn't set correctly. [(From the Qt documentation)](https://doc.qt.io/qt-5/highdpi.html) 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 + 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 @@ -136,7 +151,7 @@ To force GBM as a backend, set the following environment variables: ## Theming Related Variables - `GTK_THEME` - Set a GTK theme manually, for those who want to avoid appearance - tools such as lxappearance or nwg-look + 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](../../FAQ/) for why you might