IMPORTANT NOTE: LeftWM has changed the config language from TOML
to RON
with the 0.4.0
release. Please use leftwm-check --migrate-toml-to-ron
to migrate your config and visit the wiki for more info.
Table of contents
- Why go left
- Dependencies
- Installation (with package manager)
- Manual Installation (no package manager)
- Theming
- Configuring
- Troubleshooting
- Support
Why go left
LeftWM is a tiling window manager written in Rust that aims to be stable and performant. LeftWM is designed to do one thing and to do that one thing well: be a window manager. LeftWM follows the following mantra:
LeftWM is not a compositor.
LeftWM is not a lock screen.
LeftWM is not a bar. But, there are lots of good bars out there. With themes, picking one is as simple as setting a symlink.
Because you probably want more than just a black screen, LeftWM is built around the concept of themes. With themes, you can choose between different bars, compositors, backgrounds, colors, docks, and whatever else makes you happy.
LeftWM was built from the very beginning to support multiple screens and ultrawide monitors. The default keybindings support ultrawide monitors and multiple screens.
One of the core concepts/features of LeftWM is theming
With LeftWM, there are two types of configuration files:
-
LeftWM Configuration files: LeftWM configurations are specific to you and don’t change for different themes. These are settings like keybindings, workspace locations, and names of desktops/tags. These settings can be found in
~/.config/leftwm/config.toml
. -
Theme Configuration files: The appearance of your desktop is different. It’s fun to try new looks and feels. It’s fun to tweak and customize the appearance (AKA: ricing). It’s fun to share so others can experience your awesome desktop! LeftWM is built around this concept. By pulling all these settings out into themes, you can now easily tweak, switch, and share your experiences. This configuration is spread between
theme.toml
and related files contained within a theme's folder.
Dependencies
While LeftWM has very few dependencies, this isn't always the case for themes. Themes typically require the following to be installed. However, this is up to the author of the theme and could be different.
List of LeftWM dependencies:
- xorg (runtime, build): specifically libx11, xrandr, xorg-server, libxinerama
- sh (runtime): any posix-compliant shell for starting up and down files
- rust (build): >= 1.56.0
- bash (optional): Most of the themes available use bash, though the scripts maybe converted to any posix-compliant shell
List of common dependencies for themes:
Dependency (git) |
Ubuntu 20.4.1 sudo apt install {} |
Arch sudo pacman -S {} |
Fedora 33 sudo dnf install {} |
PKGS |
---|---|---|---|---|
feh | feh | feh | feh | feh |
compton | compton | picom | compton | compton |
picom | manual ** | picom | picom | picom |
polybar | manual ** | polybar | polybar | polybar |
xmobar | xmobar | xmobar | xmobar | xmobar |
lemonbar | lemonbar | paru -S lemonbar* | manual ** | lemonbar |
conky | conky | conky | conky | conky |
dmenu | dmenu | dmenu | dmenu | dmenu |
* You can use whichever AUR wrapper you like. See paru and yay.
** See the git page (link in first column) for how to install these manually
Installation (with package manager)
GURU)
Gentoo (sudo layman -a guru && sudo emerge --sync
sudo emerge --ask --verbose x11-wm/leftwm
AUR)
Archlinux (paru -S leftwm
paru is an AUR helper like yay, but written in Rust.
copr)
Fedora (sudo dnf copr enable th3-s4lm0n/leftwm -y && sudo dnf install leftwm
Official repositories)
NetBSD (pkgin install leftwm
or, if you prefer to build it from source
cd /usr/pkgsrc/wm/leftwm
make install
XBPS)
Void (sudo xbps-install -S leftwm
crates.io)
Cargo (cargo install leftwm
If you install LeftWM with crates.io, you will need to link to the xsession desktop file if you want to be able to login to LeftWM from a display manager (GDM, SSDM, LightDM, etc.):
sudo cp PATH_TO_LEFTWM/leftwm.desktop /usr/share/xsessions
Also see the build options for more feature options, especially if you don't use systemd
or want to use your own hotkey daemon like sxhkd
.
OpenBSD)
OpenBSD (At the moment LeftWM is not packaged with OpenBSD package manager, but it could be installed via Cargo.
cargo install leftwm --no-default-features --features lefthk
leftwm-config
not yet ported to OpenBSD, as it requires a nightly Rust compiler to build.
The default config is generated by LeftWM when it is first started.
To start LeftWM with xenodm
add the following to your ~/.xsession
. Make sure to remove or comment-out the exec
to the previous WM you had there.
exec dbus-launch ~/.cargo/bin/leftwm >> ~/.cache/leftwm.log 2>&1
Manual Installation (no package manager)
Using a graphical login such as LightDM, GDM, LXDM, and others
-
Dependencies: Rust, Cargo
-
Clone the repository and cd into the directory
git clone https://github.com/leftwm/leftwm.git cd leftwm
-
Build leftwm
cargo build --profile optimized
For more options see the build options section.
-
Copy leftwm executables to the /usr/bin folder
sudo install -s -Dm755 ./target/optimized/leftwm ./target/optimized/leftwm-worker ./target/optimized/lefthk-worker ./target/optimized/leftwm-state ./target/optimized/leftwm-check ./target/optimized/leftwm-command -t /usr/bin
-
Copy leftwm.desktop to xsessions folder
sudo cp leftwm.desktop /usr/share/xsessions/
You should now see LeftWM in your list of available window managers. At this point, expect only a simple black screen on login. For a more customized look, install a theme.
Optional Development Installation
If your goal is to continuously build leftwm and keep up to date with the latest releases, you may prefer to symlink the leftwm executables instead of copying them. If you choose to install this way, make sure you do not move the build directory as it will break your installation.
Note that if you want to build leftwm with an other build profile, you will have to change the
--profile <profile-name>
option and the target folder to target/<profile-name>
.
Currently available are dev
, release
and optimized
.
-
Dependencies: Rust, Cargo
-
Clone the repository and cd into the directory
git clone https://github.com/leftwm/leftwm.git cd leftwm
-
Build leftwm
# With systemd logging (view with 'journalctl -f -t leftwm-worker') cargo build --profile optimized
For more options see build options below.
-
Create the symlinks
sudo ln -s "$(pwd)"/target/optimized/leftwm /usr/bin/leftwm sudo ln -s "$(pwd)"/target/optimized/leftwm-worker /usr/bin/leftwm-worker sudo ln -s "$(pwd)"/target/optimized/lefthk-worker /usr/bin/lefthk-worker sudo ln -s "$(pwd)"/target/optimized/leftwm-state /usr/bin/leftwm-state sudo ln -s "$(pwd)"/target/optimized/leftwm-check /usr/bin/leftwm-check sudo ln -s "$(pwd)"/target/optimized/leftwm-command /usr/bin/leftwm-command
-
Copy leftwm.desktop to xsessions folder
sudo cp leftwm.desktop /usr/share/xsessions/
You should now see LeftWM in your list of available window managers. At this point, expect only a simple black screen on login. For a more customized look, install a theme.
Rebuilding the development installation
-
Now if you want to get the newest version of leftwm run this command from your build directory:
git pull origin main
-
Build leftwm
# With systemd logging (view with 'journalctl -f -t leftwm-worker') cargo build --profile optimized
-
And press the following keybind to reload leftwm
Mod + Shift + R
Optional Build Features
Since LeftWM
is targeting to be more and more modular, there are a few features that can be selected at compile time:
Use cargo
with the added flags --no-default-features --features=
and then commaseparated a selection from the following features:
feature | info | default |
---|---|---|
lefthk | built-in hotkey daemon, if you build with out make sure you bring your own (e.g. sxhkd ) to manage any keybinds, be sure you install the lefthk-worker binary if you build with this option |
|
journald-log | logging to journald , depends on systemd |
|
sys-log | use standard system logging | ✘ |
file-log | log to /tmp/leftwm/<log-file-by-datetime-of-launch> |
✘ |
Example:
# With `lefthk` and logging to `sys-log`
cargo build --profile optimized --no-default-features --features=lefthk,sys-log
# Without `lefthk` and logging to file
cargo build --profile optimized --no-default-features --features=file-log
There are also multiple levels of optimization. These are specified by the cargo profiles, available are dev
, release
and optimized
. The dev and release profiles are default profiles used by cargo, whereas the optimized profile is recomended for production builds.
Example:
# With the dev profile
cargo build --profile dev
# With the release profile
cargo build --profile release
Using the Makefile
For conveniece we also have a Makefile with the following rules:
make ... | info |
---|---|
all | implies build and test |
test | runs same tests as CI on github |
test-full | same as test but additionally with pedantic clippy lints |
test-full-nix | same as test-full but additionally compiles the nix package, resulting in a full representation of ci checks |
build | builds with cargo profile optimized by default; read build output on how to change the profile. |
clean | clean all buildfiles |
install | install by copying binaries to /usr/bin , also places leftwm.desktop file to /usr/share/xsession and cleans build files |
install-linked | installs by symlinking, copies leftwm.desktop , no clean |
uninstall | removes leftwm-* files from /usr/bin and leftwm.desktop file |
Note that for build
, install
and install-linked
, you can specify the build profile to use by adding the profile=<profile-name>
argument. Currently available are dev
, release
and release-optimized
.
Starting with startx or a login such as slim
Make sure this is at the end of your .xinitrc
file:
# .xinitrc
exec dbus-launch leftwm
On some distros like Archlinux, the environment variables are being setup by sourcing /etc/X11/xinit/xinitrc.d
, as described in the Arch docs, please make sure you copy the default xinitrc like this:
cp /etc/X11/xinit/xinitrc ~/.xinitrc
Note: In this case it is not necessary to start leftwm through dbus-launch
and might even result in some cases in services like gnome-keyring
to fail. In such an occasion just use:
# .xinitrc
exec leftwm
Theming
If you want to see more than a black screen when you login, select a theme:
LeftWM-Theme
Withleftwm-theme update
leftwm-theme install NAME_OF_THEME_YOU_LIKE
leftwm-theme apply NAME_OF_THEME_YOU_LIKE
LeftWM-Theme
Withoutmkdir -p ~/.config/leftwm/themes
cd ~/.config/leftwm/themes
ln -s PATH_TO_THE_THEME_YOU_LIKE current
LeftWM comes packaged with a couple of default themes. There is also a community repository for sharing themes.
For more information about themes check out our theme guide or the wiki.
Note: leftwm uses RON now as its default config language. Please consider migrating your toml configs.
Configuring
You can configure key bindings, default mod key and many other options:
LeftWM-Config
Withleftwm-config -n # Generate new config
leftwm-config # Open configuration file in $EDITOR
leftwm-config -t # Edit configuration via TUI (Beta)
Without via editing the file
~/.config/leftwm/config.ron
Note: The configuration file is automatically generated when leftwm or leftwm-check is run for the first time.
Note: leftwm uses RON now as its default config language. Please consider migrating your toml configs.
Default keys
Keybinding | Description |
---|---|
Mod + (1-9) | Switch to a desktop/tag |
Mod + Shift + (1-9) | Move the focused window to desktop/tag |
Mod + W | Switch the desktops for each screen. Desktops [1][2] changes to [2][1] |
Mod + Shift + W | Move window to the other desktop |
Mod + ( |
Focus on the different windows in the current workspace |
Mod + Shift + ( |
Move the different windows in the current workspace |
Mod + Enter | Move selected window to the top of the stack in the current workspace |
Mod + Ctrl + ( |
Switch between different layouts |
Mod + Shift + ( |
Switch between different workspaces |
Mod + Shift + Enter | Open a terminal |
Mod + Ctrl + L | Lock the screen |
Mod + Shift + X | Exit LeftWM |
Mod + Shift + Q | Close the current window |
Mod + Shift + R | Reload LeftWM and its config |
Mod + p | Use dmenu to start application |
Note: Although we encourage you to use Alacritty, LeftWM will set your default terminal to the first terminal it finds in this list (in the order presented):
- Alacritty
- Termite
- Kitty
- URXVT
- RXVT
- ST
- ROXTerm
- Eterm
- XTerm
- Terminator
- Terminology
- Gnome Terminal
- XFCE4 Terminal
- Konsole
- UXTerm
- Guake
Floating Windows
You can optionally switch between tiling or floating mode for any window.
Keybinding | Description |
---|---|
Mod + MouseDrag | Switch a tiled window to floating mode |
Mod + RightMouseDrag | Resize a window |
Drag window onto a tile | Switch a floating window to tiling mode |
Mod + Shift + (1-9) | Switch a floating window to tiling mode |
Workspaces
By default, workspaces have a one-to-one relationship with screens, but this is configurable. There are many reasons you might want to change this, but the main reason is for ultrawide monitors. You might want to have two or even three workspaces on a single screen.
Here is an example config changing the way workspaces are defined (~/.config/leftwm/config.toml)
workspaces: [
( y: 0, x: 0, height: 1440, width: 1720 ),
( y: 0, x: 1720, height: 1440, width: 1720 ),
],
You may optionally specify an ID for your defined workspaces. This is helpful if you want to assign different gutter settings to each workspace in your theme.
workspaces: [
( y: 0, x: 0, height: 1440, width: 1720, id: 0 ),
( y: 0, x: 1720, height: 1440, width: 1720, id: 1 ),
],
NOTE You do not have to define an ID for each workspace, but if you assign an ID to one workspace all subsequently defined workspaces without an ID will be assigned an ID incrementing from the largest ID currently assigned to any workspace. In the above example if the second workspace was not defined with ID = 0 it would be assigned ID = 2. Keep this in mind when creating or customizing themes.
Tags / Desktops
The default tags are 1-9. They can be renamed in the config file by setting the list of tags.
Here is an example config changing the list of available tags. NOTE: tag navigation (Mod + #) doesn't change based on the name of the tag.
tags: ["Web", "Code", "Shell", "Music", "Connect"],
Layouts
By default, all layouts are enabled. There are a lot of layouts so you might want to consider only enabling the ones you use. To do this add a layout section to your config.toml file. This enables only the layouts you specify.
Example:
layouts: ["MainAndHorizontalStack", "GridHorizontal", "Fibonacci", "EvenVertical", "EvenHorizontal", "CenterMain", "CenterMainFluid"],
Layouts may also be specified on individual workspaces, this is useful if you have monitors with different aspect ratios or orientation.
Example:
workspaces: [
( id: 0, y: 480, x: 0, height: 1600, width: 3840,
layouts = ["CenterMain", "CenterMainBalanced", "EvenHorizontal"]),
( id: 1, y: 0, x: 3840, height: 2560, width: 1440,
layouts = ["MainAndHorizontalStack", "EvenVertical"]),
],
NOTE When defining layouts per workspace, you will need to define workspace IDs explicitely.
More detailed configuration information can be found in the Wiki.
EWMH compliant
LeftWM isThe default layouts are all of the kinds described by the Layout enum.
Troubleshooting
Issue | Description | Solution |
---|---|---|
LeftWM not listed by login manager | You likely need to add the xsessions file to the right folder. | See installation |
No config.toml file exists | LeftWM does not always ship with a config.toml . You will need to execute LeftWM at least once for one to be generated. |
Try the following: leftwm-worker |
Config.toml is not being parsed | LeftWM ships with a binary called leftwm-check. It might not be installed by the AUR. | Try the following: leftwm-check |
Keybinding doesn't work | It's likely you need to specify a value or have a typo. | See Wiki |
Support
LeftWM now has a Discord channel for faster help.