Beginner's Quick Start Guide to Endeavour OS Bspwm Edition

Hi there! :wave:

I compiled/typed some basic tips and info for users new to Bspwm. Most of this is general information. Some stuff in the Polybar section is specific to the config that is bundled with our Bspwm edition.

This is aimed at users who are totally new to the environment and want info to get started with editing configs. :sparkles:

Installing the Endeavour OS Bspwm Edition

Download the ISO from the links given on the post here :point_up:

On the Welcome app, choose Install Community Editions and from the window that opens up, click Bspwm.

To run the config on an existing install of Endeavour OS run following commands in terminal

git clone
cd bspwm

This will get the latest dotfiles from the repo, install packages/fonts and rebuild font cache. Log out. On the login screen, choose Bspwm as your environment and login. You should now see the Bspwm edition :partying_face:


Bspwm is Binary Space Partitioning Window Manager. This is a tiling window manager. If you come from a traditional desktop environment like Xfce, you notice that the primary way of managing open windows is the mouse. Those are floating window managers. :swan:

Then there are tiling window managers, where all windows are visible on the desktop and are automatically arranged so as to fill the complete screen real estate. A tiling window manager doesn’t mean it needs to be controlled via the keyboard, however, the way they function, it is very efficient to use keyboard shortcuts to control your windows.

Bspwm only manages your windows. The keyboard shortcuts are handled by a different program called sxhkd. This is different than i3wm, where the window manager manages your keyboard shortcuts also. :keyboard:


bspwm is a tiling window manager that represents windows as the leaves of a full binary tree. :palm_tree:

bspc is a program that writes messages on bspwm’s socket. :electric_plug:

When a program is run, it is placed in a tree, splitting the current branch. Windows can have 4 states - tiled, pseudo_tiled, floating and full screen.

  • Tiled means the window’s size will fill up the maximum area possible without overlapping other windows around it. It will stay in it’s set location based on it’s position in the window tree.

  • Pseudo Tiled is the same as tiled except the window can be resized at will. The position stays the same though.

  • Floating means the window can be placed anywhere on the desktop and resized at will.

  • Fullscreen is pretty self explanatory.


Bspwm settings are modified via running shell commands. If you run the same commands every time bspwm starts up, you will get the same configuration. You surely do want some commands to be run whenever bspwm starts, like window border related settings, startup apps etc. These are defined in ~/.config/bspwm/bspwmrc. This file will contain the bspc commands that will be run at startup. It is actually a shell script that bspwm runs at startup so you can put any other shell command you want. You can also use loops, if-else constructs in case you want to do something complex and fancy. (like applying different settings based on the display resolution. That way you can run the same config file across all your systems and still get pixel values tailored to the specific monitor it runs on. :desktop_computer:

Keybindings are defined in ~/.config/sxhkd/sxhkdrc. Apart from bspwm related keybindings, you can also put keybindings for commonly used commands. For eg. I am usually ssh-ing into a system on my network, so I add a command to open terminal and run the ssh command. This is bound to a keyboard shortcut. You can also bind shortcuts to launch commonly used applications. Another thing I recommend binding is the music controls if you use Mpd.

Its totally up to you. Different people have different uses and you can bind whatever you regularly use. Makes your workflow faster. :sparkler:

Bspwm is very feature rich. This is just an introduction; look up on the internet for lot more things you can do with it.

Extra reading :

  1. Readme at explains well how windows are managed.
  3. A post by @manyroads where they describe their journey while setting up Bspwm. Note they follow a different install process, since they were on a different distro. However, the configs suggested here are interesting and useful.


The official wiki on their GitHub is pretty good. You just need to copy paste the relevant module code in your config file and change the values of variables.

In the config bundled with our Bspwm edition, there is a section at the beginning where all the colors are defined. You can directly put in hex codes wherever a color value is required, but having them all defined at one place as variables make it a bit easier to manage. :rainbow:

How it works?

Polybar config consists of bar definitions and module definitions. You can have multiple bars defined in one config file. Each bar has settings about its size, border, padding, position etc.

Modules are the units that you place on the bar. They can show basic system info like CPU usage, Ram usage, or WM related info like workspaces. You can also create custom modules to show the output of a script on the bar.

Each bar can have one or more modules place in one of the three alignments - left, center or right. (modules-left, modules-center and modules-right) The bar does not need to have all the modules place on it. You can define many modules and use only a few of them if you like. In fact, the Polybar config with our Bspwm edition has three modules that are defined but are not there on the bar by default.

Start/Re-start Polybar

Polybar can be started from the terminal using the command below:

polybar [bar-name] -c /path/to/config 

Add the -r flag if you are editing/testing config. This flag makes polybar automatically restart when the config file is updated.

In our Bspwm edition, we have used a launch script to first terminate any running instances of polybar and then start a new instance of polybar. The file can be seen here on GitHub.

So if you’re running our configs, then all you need to do is to run ~/.config/polybar/ in a terminal.

System Tray

In Polybar, system tray is not a module. It can be aligned to left, right or center. But it cannot be positioned between other modules. Also, you will notice that it is not there in active modules list. System tray is enabled by adding a value to tray-position property.

Disabled modules

In the Bspwm edition, there are some disabled modules. I added them because many people like to use it, but kept them disabled since its not something I wanted on a default config. To enable them, you just need to add the corresponding module name where the active modules are listed.

  • Network speed indicator :cloud: - Displays real time network speed on the bar. You need to set the correct interface name for your network in module definition. (modules are defined in the same config file).
    Module name is netspeed. Add this to the modules list and restart Polybar.

  • Mpd Info :musical_note: - Shows current playing track info in Artist - Track format. You need to have a running Mpd instance. In the module definition, you need to set the correct host and port for Mpd.
    Module name is mpd.
    Note that Mpd or its configs are not bundled with our Bspwm edition. If you are new to Mpd and want to set it up, you can read the relevant Arch Wiki entry, or create a thread on our forum. I’ll be happy to help you in case you face any roadblocks.

  • Mpd Controls :headphones: - Shows previous, play/pause, next button to control music playback via Mpd. Again, you need to set the correct host and port in module definition.
    Module name is mpd_control.

  • Pending Updates - This module shows a number on your bar indicating the number of packages that can be updated. Module name is checkupdates.
    Note that this module is different from the eos-update-notifier.

For PC Users

Our config comes with a backlight and battery module by default. They are for laptop users. On a PC with AC supply, those modules are automatically disabled by Polybar on startup. So you don’t need to worry about having redundant modules on your bar. You can go ahead and remove them too if you like.

Extra Modules

There are GitHub repositories that collect user written modules/scripts that are meant to be used with Polybar.
Two such popular repos are polybar/polybar-scripts and TiagoDanin/Awesome-Polybar.

External links:

  1. Polybar Wiki Home :

More Configs


Rofi is used to show the app launcher and powermenu. Rofi settings are defined in ~/.config/rofi/config.rasi. The default config is pretty basic and you can customize Rofi very much.

Powermenu script is in the same folder, with name At the beginning of script, you have the options defined as variables. You may edit them if you want a different icon or different text for the options. This script also lets you change the order in which the options are displayed, by changing the order in echo statement.


Dunst shows your notifications. Config is located in ~/.config/dunst/dunstrc. You can change the colors, position etc.

One important setting you may want to change is the binding for Ctrl + grave. By default, this is used to show notification history. Useful in case you miss a notification or want to see the details again. The keybinding may conflict with other applications. For example, the same keybinding is also used in Code-OSS/VSCode. To disable the behaviour in dunst, open dunstrc file and comment out line 270.

To comment it, you simply put a pound symbol at beginning of line.


We use Nitrogen to set/change wallpaper.

To change the wallpaper, open Nitrogen application. Click on “Preferences” and on the pop up, add your wallpaper directory to the list. Save it and now Nitrogen will display your wallpapers from which you can choose the one to set.

In case you want to use a different application to set wallpaper, open ~/.config/bspwm/bspwmrc file and comment out or remove the line that says nitrogen --restore &. Then you can go forward to setting up whichever wallpaper setter you want to use.

Transparency/ Compositor

We use picom for compositing. Config file is ~/.config/picom.conf. You may want to change the transparency values or enable background blur.

Resolution and Arandr

When you log in for first time, resolution may be too less. You can use the “Change Display Resolution” on welcome app. Resolution will increase, but you need to reload Bspwm now. Press Mod+Alt+r.

To make it permanent, open Arandr, and save your resolution (last button on toolbar). Save it in ~/.screenlayout/ as file name
You may need to create ~/.screenlayout folder.

Now when you reboot and log in, your resolution will be reloaded.

Feel free to share your suggestions and criticism. :pray:
I’ll keep updating this post as and when required.

Snehit Sah


Very nice! Some of this could be possibly be added to wiki page if the team likes it?


Thanks! This is helpful to a newbie to tiling window managers … gives me what I need to understand where and how things are configured. I’ve been enjoying the i3 version and am planning to play with bspwm to compare my experience. Seems like bspwm is a bit more flexible?


Welcome aboard!

1 Like

Maybe I missed it. . . when/where/how can I give this a spin? Is it already available on the installation iso?

1 Like
1 Like

I downloaded the Dev .iso, it came with the appropriate warning so I know it’s correct. Online install doesn’t show bspwm though. I have the normals - xfce, mate, kde, (deepin beta v20) . . . i3, no bspwm though.

Internet is connected. Everything else looks correct. Is it just base level and then install bswpm on my own?

Edit: I found it. Welcome center - community editions. Got it!

1 Like

There is a button on the welcome app. I believe it says install community versions. Click that and you will have two options to click. Sway and bspwm. Sway has an additional option to install the zen kernel. Bspwm does not. At least the last time I installed them.

1 Like

Installing to bare metal with a swap file. Let’s see what I can break this morning.


Welcome! :wave:
i3 is simpler in terms of features and is a good choice for a first window manager to someone who never tried a wm before.
Bspwm has a different style of configuration (shell scripts) so there is definitely more possibilities. Also, it is very easy to change wm settings on the fly. Bind two two totally different configs to different keybindings and switch between them easily.
The major difference I would say is in the way Bspwm manages windows. Its like a tree. Bspwm can automatically switch layouts without losing on the hierarchy. i3 is a manual tiler, while Bspwm is an automatic tiler. There are more tiny nifty features you’ll discover as you keep using Bspwm.

There are a bit more keybindings in Bspwm as compared to i3. You’ll get used to it pretty quick.

1 Like

FWIW Here’s a bunch of material I wrote while I was testing/ building/ using bspwm:


Added a section on installing the Bspwm edition just in case someone else missed it too.

1 Like

It was there, I just initially clicked on the normal “install” and didn’t see it.

So far it’s going alright. Some of my keys don’t work - it seems like my Fn+Fkeys don’t seem to be working. Or maybe my Fn key at all. . . I put in US default 105 as usual, - this is a Dell 7548 laptop US model. I’m looking through the keybinding config now to see what’s going. My volume keys don’t work, nor my display brightness. Im looking into it

It seems meta+q and meta+shift+q do the same thing. I’m swapping it to meta+x now (my normal preference.)

Rofi works great so far, and I love it!

It’s more than enough to get me moving though! Thanks for all of your effort so far. It looks beautiful - Colors, gaps, etc.


Thanks :blush:

I did a VM install and I face the same issue. Keys were working until Wednesday. I’ll probe it. Thanks for reporting. :pray:

Also not working in my VM snapshot of Wednesday :scream:

1 Like

This is why we test things. :slight_smile: Again, thanks for your work, and sorry to make more for you.

Is there a way to move a window - say firefox from one of the workspaces to another? For instance I opened it in the first workspace next to the “start/power” icon on polybar. Can I move it one more to the right to the “firefox” workspace? I don’t see it in the bindings anywhere.


Not a problem at all :handshake:
The more we test right now, the more bugs we spot early, before this goes into the actual ISO.

To move the active window, you press Super + Shift + <number>.
Like Super+Shift+4

1 Like

There it is.

Going through and it seems the keybindings and everything seem to work well. There’s a few I can’t use because of the topkeys not quite working right. I’ll keep playing with it though. I’ve never really used bspwm, but I’ve done quite a bit with i3. I really like this though. I will do some more testing shortly.

I would probably also add the meta+tab and meta+[ and meta +] bindings to the quick pop up keybinding thing. I think those are two most people would want to know out of the gate.

Edit - then again I can’t open the meta + F1 full list helper currently. Maybe that is in there.

1 Like

The config work as expected on a bare metal install!

Audio controls working fine. But couldn’t get it to work in my VM :thinking:

I’ll see tomorrow if some idea pops up in my lazy brain or someone else has any pointers.

For the keybindings pop up, There is a blue “i” button right beside the workspaces on the bar. You can click it to see the keybindings. Know that the list there is just a filler of sorts. Doesn’t have much as of now.

1 Like



It looks a bit awarkward when you add more then maybe 7 things cause it a really big pop-up then! Maybe change the keybinding to open full list? Not mod+f1?