bspwm-dotfiles: an Arch Linux desktop and its builder script in one repository
A minimalistic Arch Linux build that is designed to make your development easier and faster
At a glance
- What is it?
- Zproger's bspwm-dotfiles is an Arch Linux configuration built around BSPWM, Polybar, Picom, Alacritty, Rofi, Dunst and Fish, shipped with a Builder that installs the base system and the shell, plus hotkeys, wallpaper tooling and post-installation fixes. It is a complete desktop recipe for a 1920x1080 screen, and the recipe assumes a lot about your machine and your username.
- Who is it for?
- bspwm-dotfiles fits an Arch Linux user who wants a complete keyboard-driven desktop with a working BSPWM tiling setup rather than a set of loose config fragments, and it does not fit a machine with a non-1920x1080 display, a hardware video driver stack the builder cannot install, or a username other than user.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 44 days ago.
- What is it written in?
- Mainly CSS, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on October 22, 2026, and from our analysis. They are not legal advice.
Editorial analysis
A whole desktop, not a set of config fragments
The repository describes itself as a minimalistic Arch Linux build designed to make your development easier and faster, and the name is a bit misleading about the scope. There is a window manager configuration, a bar, a compositor, a terminal, an application launcher, a notification daemon and a shell, and on top of that there is a Builder directory, a bin directory of scripts, a firefox directory, a themes directory and a set of documentation.
The component list in the readme is the whole stack:
- OS: Arch Linux - WM: BSPWM - Bar: Polybar - Compositor: Picom - Terminal: Alacritty - App Launcher: Rofi - Notify Daemon: Dunst - Shell: Fish
Two features deserve a second look because they say what kind of artefact this is. Support for over 300 dynamic wallpapers, and a very lightweight system that consumes less than 700mb of memory. A static wallpaper set is a matter of taste, whereas a wallpaper that follows the desktop and reacts to it needs a script and a working compositor, and it is a good indicator of how much of the system is wired together rather than merely configured.
The stated features also include automatic installation and configuration of all basic software for development, which is the Builder's job, and convenient custom configuration of Firefox, which explains the firefox/ directory in the tree.
The Builder: base system and graphical shell in one pass
The installation section points to a guide rather than to a command, and that is the most important structural fact about the project. The readme links two documents, one in English and one in Russian, both titled installing arch linux with bspwm, under Docs/. The English one is Docs/01_installing_arch_linux_with_bspwm_english.md and the Russian one is Docs/00_installing_arch_linux_with_bspwm_russian.md.
So the installation path is a guide for the Builder, and the Builder directory at the top level of the repository is the script that guide drives. This is a different model from a dotfiles repository you clone and symlink, and it is a different model again from a plain install script. You follow a document that installs Arch Linux and then the graphical shell via the builder.
That difference matters for anyone evaluating it. A symlink dotfiles repository is trivial to try and trivial to undo. A builder that installs an operating system and a shell is a commitment, and the readme's own list of post-installation problems is a measure of how much can need fixing afterwards.
The documentation set is also where the real content lives. There are two feature documents, Docs/03_all_features_and_tricks_english.md and Docs/02_all_features_and_tricks_russian.md, which the readme links as the complete feature list, alongside the two installation guides. The repository also has an UPDATES.md file at the top level, and the readme points at the Projects tab on GitHub for tracking current shell updates.
The hotkey map, and where the rest of it lives
The readme lists a compact hotkey set, and it is worth reading as a description of the intended workflow rather than as a list to memorise.
Opening the terminal is bound to super + enter, and the application menu to super + d, both of which sit under the super key as a two-key combination. super + w sets a random wallpaper, which pairs with the wallpaper support in the feature list. super + space switches the focused window to floating mode, which is the one piece of BSPWM behaviour that a mouse user feels immediately, and super + c closes the focused window. Layout switching is shift + alt, and super + 1/6 switches desktops while super + shift + 1/6 moves the window to another desktop.
The rest of the bindings are less obvious. super + shift + q derives a random verse from the Bible, super + shift + x recognises the colour on the screen, super + shift + k opens a console calendar, super + shift + t launches Telegram, super + shift + i opens the browser in incognito mode, super + shift + l locks the screen, and super + v opens the clipboard manager. Screenshot is on print, and ctrl + shift + r restarts bspwm, which is the key to know when a config edit has broken something.
The readme notes that the other hotkeys are in ~/.config/sxhkd/sxhkdrc. That is the actual mechanism: sxhkd is the key handler, and the readme table is a summary. sxhkd is not in the component list at the top of the readme, which is a small sign that the summary is not the whole configuration.
The screen resolution assumption is stated as a warning
The readme puts a warning table in the middle of the document, and it is the single most important constraint for anyone considering this setup. The configuration is designed for 1920x1080 monitors, some functionality of the shell may not work as it should in that case, and adjustments need to be made manually.
That is repeated in the post-installation section as the interface problem: if you are not using a 1920x1080 monitor, the interface may not look like it should, and the configuration needs to be edited manually.
The reason is not mysterious. BSPWM, Polybar and Rofi all work in absolute pixels, and a configuration that positions a bar and lays out panels for one exact resolution is not going to look right on a 2560x1440 panel or a 1920x1200 laptop screen without arithmetic. Since the project provides no scale or density settings of its own, that work falls to the user.
The readme asks readers who find errors in the shell to report the problem, and separately asks people who find bugs not on the list and are sure they followed the manual to get in touch, so there is a support path, but the resolution constraint is not a bug and will not be fixed by it.
Post-installation fixes: drivers, battery, picom and the username
The post-installation section is the most useful part of the readme for a prospective user, because it tells you in advance what will break.
The brightness of the screen is not displayed on the bar, and the reason given is that the builder was unable to automatically install drivers for the video card or processor, so you have to go to the Arch Wiki and do the installation manually. That is a significant admission: the driver stack is the part of an Arch installation most likely to differ per machine, and this builder does not handle it.
The battery is not displayed on the bar, and the fix is to edit ~/.config/polybar/modules.ini and adjust the [module/battery] module to match your battery and adapter data, following the polybar instructions. Hangs in the animation or terminals are attributed to missing graphics drivers or working from a virtual machine, and the fix is to open ~/.config/bspwm/bspwmrc and comment out the line with the picom startup.
The last one is a hard constraint rather than a fix. The configuration is installed locally on the user from where the builder was running, and the username must be user for the system to work properly; if you get a user name error, you have to create a new user named user and redo the installation.
There is also a video of the corrections at a YouTube link, which is the quickest route if you would rather watch the edits than read them.
MIT licensed, no releases, and a builder that keeps changing
The licence is MIT, with the LICENSE file at the top level of the repository. The repository is not archived, and the last push was on 2026-09-08. There are no GitHub releases at all, so there is no version history to point at, and the readme says the project is actively developing and invites ideas for improvements, with a YouTube channel and a Telegram group linked for that purpose.
That combination, a builder script plus a live documentation set plus a changing shell, has a practical consequence. There is no tagged version to pin, so if you install today you get whatever the repository contained today, and the fixes in the post-installation section may or may not have been folded into the builder yet. The UPDATES.md file and the Projects tab are the substitutes for a changelog, and you have to go looking for them.
The tree itself shows the parts: Builder/, Docs/, Images/, bin/, config/, demonstration/, firefox/, local/, themes/, plus a gtkrc-2.0, an Xresources file and an xinitrc at the root. The Xresources and xinitrc are the older X11 session entry points, which fits a BSPWM setup that starts from a session rather than from a display manager.
The repository also carries a demonstration directory with seven screenshots, which is a reasonable way to judge the result before committing to the installation.
Editorial conclusion
bspwm-dotfiles fits an Arch Linux user who wants a complete keyboard-driven desktop with a working BSPWM tiling setup rather than a set of loose config fragments, and it does not fit a machine with a non-1920x1080 display, a hardware video driver stack the builder cannot install, or a username other than user. Before running the Builder, read the installation guide in Docs/, check that your graphics drivers are installed beforehand, and plan for the fixes the readme lists, since the battery module and the picom startup line both need manual attention on a real laptop.
Frequently asked questions
What is bspwm-dotfiles and what does it include?
It is an MIT licensed Arch Linux desktop configuration built around BSPWM, with Polybar, Picom, Alacritty, Rofi, Dunst and Fish, plus a Builder script, wallpaper tooling, a bin directory of scripts and custom Firefox configuration. The project states that the system consumes less than 700mb of memory and supports over 300 dynamic wallpapers.
How do I install the bspwm-dotfiles system?
The readme points to a guide rather than a single command, with an English and a Russian document under Docs/ describing installing Arch Linux with BSPWM via the builder. The Builder directory at the top of the repository holds the script that guide drives, and the readme also links a video of the post-installation corrections.
Does bspwm-dotfiles work on a monitor that is not 1920x1080?
Not out of the box. The readme carries a warning that the configuration is designed for 1920x1080 monitors, that some functionality of the shell may not work as it should otherwise, and that the interface may not look right, in which case the configuration has to be edited manually.
What has to be fixed after installing bspwm-dotfiles?
The listed fixes are the bar brightness when the builder could not install graphics drivers, the battery module in ~/.config/polybar/modules.ini, hangs caused by commenting out the picom startup line in ~/.config/bspwm/bspwmrc, and a username error, since the configuration is installed for a user named user and a new one must be created and the installation redone.
Where are the bspwm-dotfiles hotkeys configured?
The readme lists a summary of the main bindings, such as super + enter for the terminal, super + d for the application menu, super + space to float the focused window and ctrl + shift + r to restart bspwm. The other hotkeys are in ~/.config/sxhkd/sxhkdrc.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/zproger-bspwm-dotfiles)Was this useful?