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:

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:

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:

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:

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