Configuration

Recommended Packages for New Users #

Looks #

Install all of the official Regolith looks:

sudo apt install regolith-look-*

Alternatively, apt will list available looks that may be installed:

apt list | grep regolith-look-

NOTE: this may pull in fonts, themes, and wallpapers. For users looking to minimize disk usage, uninstalling looks that are unused is recommended.

See below for details on how to select a look.

Status Indicators #

The following snippet installs status indicator packages recommended for new users:

sudo apt install i3xrocks-focused-window-name i3xrocks-rofication i3xrocks-info i3xrocks-app-launcher i3xrocks-memory

To remove any of these indicators later, simply uninstall them from your system. Example:

sudo apt remove i3xrocks-info

Laptop Battery Status #

View the current battery status on a laptop:

sudo apt install i3xrocks-battery

Compositors #

Compositors add visual effects to the windowing environment. By default, Regolith 3 installs the picom compositor. Users experiencing graphical issues due to specific hardware or driver limitations may want to install one of the following compositors instead:

PackageNotes
regolith-compositor-picom-glxDefault
regolith-compositor-compton-glxAn older compositor that may work better on some hardware
regolith-compositor-xcompmgrAn older compositor that may work better on some hardware
regolith-compositor-noneA pass-through package that does not run a compositor

See this How To for more details.

Wallpaper #

Most Regolith Looks provide a default desktop color or image. The wallpaper can be set by specifying the path to the wallpaper image via the Xresources key regolith.wallpaper.file.

Example, assuming the file /usr/share/backgrounds/hardy_wallpaper_uhd.png is present:

echo "regolith.wallpaper.file: /usr/share/backgrounds/hardy_wallpaper_uhd.png" >> ~/.config/regolith3/Xresources
regolith-look refresh

In the above command the property mentioned is set to the /usr/share/backgrounds/hardy_wallpaper_uhd.png change this path to any other that needs to be used.

To change the image treatment (zoom, scale, etc.) of the wallpaper image, set regolith.wallpaper.options. Options are: none, wallpaper, centered, scaled, stretched, zoom, spanned

Example:

echo "regolith.wallpaper.options: zoom" >> ~/.config/regolith3/Xresources
regolith-look refresh

To specify a color rather than an image use the Xresource key regolith.wallpaper.color.primary:

echo "regolith.wallpaper.file: " >> ~/.config/regolith3/Xresources
echo "regolith.wallpaper.color.primary: blue" >> ~/.config/regolith3/Xresources
regolith-look refresh

To specify a secondary color and gradient:

echo "regolith.wallpaper.file: " >> ~/.config/regolith3/Xresources
echo "regolith.wallpaper.color.primary: blue" >> ~/.config/regolith3/Xresources
echo "regolith.wallpaper.color.secondary: green" >> ~/.config/regolith3/Xresources
echo "regolith.wallpaper.color.shading.type: vertical" >> ~/.config/regolith3/Xresources
regolith-look refresh

Lockscreen Wallpaper #

The lockscreen wallpaper can be managed in the same way as the desktop wallpaper. The keys are the same as desktop wallpaper, but with lockscreen prefixed to wallpaper, like so: regolith.lockscreen.wallpaper.... For example, to specify a lockscreen image:

echo "regolith.lockscreen.wallpaper.file: /usr/share/backgrounds/hardy_wallpaper_uhd.png" >> ~/.config/regolith3/Xresources
regolith-look refresh

Disable Wallpaper handling #

If you wish to manage wallpaper externally to Regolith, simply specify empty values for wallpaper image and color:

echo "regolith.wallpaper.file: " >> ~/.config/regolith3/Xresources
echo "regolith.wallpaper.color.primary: " >> ~/.config/regolith3/Xresources

Status Bar Indicators #

Status indicators such as CPU load, date and time, notifications, weather, and other system info can be added or removed by installing packages. For example, to show a status indicator for your laptop battery, simply run sudo apt install i3xrocks-battery and then refresh the session using regolith-look refresh. To find what indicators are available, run apt search ^i3xrocks- or search for i3xrocks- in your favorite package manager GUI, such as Synaptic. There is more documentation available for configuring status indicators, also called “blocklets”. Here is a table of status indicators as of Regolith 2.2:

PackageStatus Function
i3xrocks-app-launcherShortcut to app launch dialog
i3xrocks-batteryBattery status
i3xrocks-bluetoothBluetooth status
i3xrocks-cpu-usageCPU utilization
i3xrocks-disk-capacityDisk utilization
i3xrocks-focused-window-nameTitle of focused window
i3xrocks-infoShortcut to Keybindings viewer
i3xrocks-key-indicatorKeyboard toggle status
i3xrocks-keyboard-layoutKeyboard layout
i3xrocks-media-playerMedia player status
i3xrocks-memoryMemory utilization
i3xrocks-microphoneMicrophone status
i3xrocks-net-trafficNetwork status
i3xrocks-next-workspaceShortcut to create new workspace
i3xrocks-nm-vpnVPN status
i3xrocks-openvpnOpenVPN status
i3xrocks-roficationNotification status
i3xrocks-tailscaleTailscale status
i3xrocks-tempSystem temperature
i3xrocks-timeSystem time
i3xrocks-updatesSystem package status
i3xrocks-volumeAudio volume status
i3xrocks-weatherLocal weather
i3xrocks-wifiName of connected wifi AP

Looks #

Colors, wallpaper, window and bar layouts and other visual factors are bundled together in Regolith and called “looks”. Looks provide a simple way of changing the entire look of the desktop. Like status bar indicators, looks are packaged and are installed and removed like any other software package. By convention, Look packages use the following naming format regolith-look-<name>. apt or a GUI package manager can be used to search for available looks. To select an installed look the keybinding super alt l presents a dialog:

Alternatively, the terminal command regolith-look can be used to change looks and refresh the active session with the selected look. Here’s an example that switches to the gruvbox look:

apt search ^regolith-look-
[...]
regolith-look-gruvbox/unknown,now 0.4.6-1regolith amd64
[...]
sudo apt install regolith-look-gruvbox
regolith-look set gruvbox
regolith-look refresh

To simply install all available looks:

sudo apt install regolith-look-*

i3 Features #

Starting with Regolith 2.0, many aspects of i3 configuration are managed via the package manager. Regolith provides all of its i3 configuration via “config partials”. These packages install their i3 config partials into /usr/share/regolith/i3/config.d. By installing and removing packages, i3 configuration can be customized for specific preferences. By default, when the regolith-desktop package is installed, these configuration elements are also installed as soft dependencies:

PackageFunctionFile
regolith-i3-base-launchersLaunch terminal and browser/usr/share/regolith/i3/config.d/15_base_launchers
regolith-i3-default-styleWindow behavior/usr/share/regolith/i3/config.d/40_default-style
regolith-i3-navigationNavigation keybindings/usr/share/regolith/i3/config.d/30_navigation
regolith-i3-networkmanagerNetwork and wifi functions/usr/share/regolith/i3/config.d/88_network-manager
regolith-i3-next-workspaceWorkspace utility/usr/share/regolith/i3/config.d/40_next-workspace
regolith-i3-resizeResize keybindings/usr/share/regolith/i3/config.d/50_resize-mode
regolith-i3-sessionSession keybindings/usr/share/regolith/i3/config.d/55_session_keybindings
regolith-i3-unclutterHide mouse cursor when unused/usr/share/regolith/i3/config.d/86_unclutter
regolith-i3-user-programsOptionally launch user programs specified in Xresources/usr/share/regolith/i3/config.d/90_user-programs
regolith-i3-workspace-configWorkspace keybindings/usr/share/regolith/i3/config.d/40_workspace-config

Soft dependencies can be removed without causing packages that depend upon it to be removed. This means that any of the listed packages can be removed. Users can make tweaks to configuration in a more stable manner by replacing a default configuration partial with their own version. This can be achieved by copying the partial to be customized into ~/.config/regolith3/i3/config.d/ and removing the original file in /usr/share/regolith/i3/config.d via apt. In this way, the unmodified config partials can continue to get updates and bug fixes without impacting user-specific configuration.

See the i3 configuration customization how-to for examples.

All i3 Configuration Packages #

The following contains a list of all i3 configuration packages available in Regolith 2.1:

PackageFunctionFile
regolith-wm-base-launchersLaunch terminal and browser/usr/share/regolith/i3/config.d/15_base_launchers
regolith-i3-compositorCompositor integration (delegates to regolith-compositor-<variant>)/usr/share/regolith/i3/config.d/80_compositor
regolith-i3-default-styleWindow behavior/usr/share/regolith/i3/config.d/40_default-style
regolith-wm-ftueFirst time user experience/usr/share/regolith/i3/config.d/84_ftue
regolith-i3-gaps-partiali3-gaps configuration (if installed, i3-gaps will replace i3)/usr/share/regolith/i3/config.d/35_i3-gaps
regolith-i3-gnomeRegolith Settings keybindings/usr/share/regolith/i3/config.d/60_config_keybindings
regolith-i3-i3xrocksi3 bar status indicators configuration/usr/share/regolith/i3/config.d/70_bar
regolith-i3-iliailia integration/usr/share/regolith/i3/config.d/20_ilia
regolith-wm-navigationNavigation keybindings/usr/share/regolith/i3/config.d/30_navigation
regolith-wm-networkmanagerNetwork and wifi functions/usr/share/regolith/i3/config.d/88_network-manager
regolith-i3-next-workspaceWorkspace utility/usr/share/regolith/i3/config.d/40_next-workspace
regolith-i3-remontoireLegacy keybindings view integration/usr/share/regolith/i3/config.d/45_remontoire
regolith-wm-resizeResize keybindings/usr/share/regolith/i3/config.d/50_resize-mode
regolith-i3-rofiLegacy desktop launcher integration/usr/share/regolith/i3/config.d/20_rofi
regolith-i3-roficationLegacy notification viewer integration/usr/share/regolith/i3/config.d/82_rofication
regolith-wm-rofication-iliaNotification viewer integration/usr/share/regolith/i3/config.d/82_rofication-ilia
regolith-i3-sessionSession keybindings/usr/share/regolith/i3/config.d/55_session_keybindings
regolith-i3-snapshoti3 workspace persistence/usr/share/regolith/i3/config.d/75_i3-snapshot
regolith-wm-swap-focusToggle back to last focused window/usr/share/regolith/i3/config.d/40_i3-swap-focus
regolith-i3-unclutterHides mouse when not in use/usr/share/regolith/i3/config.d/86_unclutter
regolith-wm-user-programsOptionally launch user programs specified in Xresources/usr/share/regolith/i3/config.d/90_user-programs
regolith-wm-workspace-configWorkspace keybindings/usr/share/regolith/i3/config.d/40_workspace-config

Keybindings #

Regolith version 3.0 onward replaces “i3-wm” with “wm” in Xresource keys. The content on this page has been updated for Regolith 3.0+. If you are using an earlier version, use “i3-wm” instead of “wm” in the key names below. For example wm.foo.bar changes to i3-wm.foo.bar for Regolith 1.x and 2.x.

The most common keybinding change is the super key. Regolith uses Xresources as the canonical source of truth for settings, which are read by various UI components. The table of Xresources keys open to user configuration is available elsewhere. To change the default super binding from the “windows” key to “alt”, add the following line to the file ~/.config/regolith3/Xresources:

wm.mod: Mod1
wm.alt: Mod4

Note: GNOME also has its own set of keybindings. When the Regolith session is first initialized, the conflicting GNOME keybindings are removed from the user settings. GNOME keybindings can be managed in the Regolith Settings app.

System Management #

The regolith-control-center app is the tool to configure locale, date, displays, networking and various other settings. Launch it via the app launcher with super space , type settings, and hit enter to launch the app. The direct keybinding is super c . The application may also be launched from a terminal with command regolith-control-center.

Further Reading #

To dig deeper, find which Howtos are available, or read the Xresources reference. Become an i3 power user by reading their user guide.

If you need more advanced configuration than Xresources provides, using i3’s configuration find how to here Staging Config Files