A Quick Introduction to StumpWM on Linux

StumpWM is a tiling, keyboard driven X11 Window Manager written entirely in Common Lisp.”

Why Use It

StumpWM will likely cut down a lot of your use of a mouse. There’s many reasons to use the mouse less, such as speed (entering in a key combination is faster than using a mouse), carpal tunnel syndrome, and so forth.

I like StumpWM because it helps keep me on the command line. I’ve had some experience with it’s predecessor, Ratpoison, while trying to set up a C201 with free software last year, and I liked the focus on one application at a time and being able to type in a few keystrokes to move between them. So, I figured StumpWM was worth a try. Recommended, even if you don’t end up sticking with it.


Within Ubuntu, changing window managers is fairly easy. You just need to install StumpWM with the apt package manager.

$ sudo apt-get install stumpwm

Then, logout and select the gear icon near the enter button and select StumpWM from the drop-down menu and login as usual.

Quick Start

On logging in, you will notice StumpWM strips out most of what is standard in most window managers. There’s no clock. There’s no dock. There’s no background. There’s no list of apps. There’s nothing to navigate multiple desktops. There’s only a blank screen with a box in the upper right corner: “Welcome to Stump Window Manager. / Type C-t ? for help.”

The first thing you’ll want to do when you log in is type: Control-t together then the letter c and the Enter key (or abbreviated: C-t c, same style as in Emacs). This creates a console, and it takes up all the screen real estate. Like Emacs, it is possible to split the screen into a variety of configurations. For simplicity here and due to my preference for dealing with one application at a time, I’ll assume a single application in the screen.

So, if you want to use Firefox, type:

$ firefox &

The &; starts firefox as a background process. You can even change your .bash_aliases file to do this automatically for you.

Of course, there are command keys for other functions: C-t a will give you the time. C-t ; quit, then press Enter to quit.

If you want to switch back and forth between the console and Firefox, you type: C-t C-t. If you have multiple windows, you can see them all and chose them from a drop-down meny by typing: C-t ". Each window also has a number listed, which you can access directly, by typing: C-t 0 (assuming the window is 0).

That’s all you need to get up and running. If you want to start customizing your configuration, I’ve also included a straight-forward .stumpwmrc configuration file below, which among other changes includes replacing C-t with s-t (Windows key + t), which is useful if you want to continue using C-t to open new tabs in Firefox without having StumpWM supersede it.

Also, this configuration file will add back in a mode line, so you can have the time, battery level and option applications with numbers, which can be useful.

;; -*-lisp-*-                                                                  
;; .stumpwmrc                                                                                                                              
(in-package :stumpwm)                                                          
;;; Configuration                                                              
;; Change prefix key to Windows key                                            
(set-prefix-key (kbd "s-t"))                                                   
;; Changing to pointer from X default to standard left                         
(stumpwm:run-shell-command "xsetroot -cursor_name left_ptr")

;; Change prefix key to Windows key                                            
(set-prefix-key (kbd "s-t"))                                                   
;; Changing to pointer from X default to standard left                         
(stumpwm:run-shell-command "xsetroot -cursor_name left_ptr")                   
;; Turn-off start-up message                                                        
(setq *startup-message* nil)                                                   
 "feh --bg-scale ~/path/to/image.jpg")   
;; Start emacs daemon                                                          
; (run-shell-command "emacs --daemon")                                         
;; Start pulseaudio                                                            
(stumpwm:run-shell-command "pulseaudio --start") 

;; Disable system bell                                                         
(stumpwm:run-shell-command "xset b off")                                       
;; Start gnome keyring                                                         
(stumpwm:run-shell-command "gnome-keyring-daemon --start --components=gpg,pkcs\
;; Mode line                                                                   
(defvar *battery-status-command*                                               
  "acpi -b | awk -F '[ ,]' '{printf \"%s%s\", $3, $5}' | sed s/Discharging/\-/\
 | sed s/Unknown// | sed s/Full// | sed s/Charging/+/")                        
(setf *screen-mode-line-format*                                                
      (list "[^B%n^b] %W^>"                                                    
      '(:eval (run-shell-command *battery-status-command* t))                  
      " | %d"))                                                                
(setf *window-format* "%m%n%s%c")                                              
(setf *mode-line-timeout* 1)  

;; Turn on the new mode line.                                                  
(toggle-mode-line (current-screen)                                             
;; Launch Terminal at Start                                                    
(stumpwm:run-shell-command "gnome-terminal")                                   
;; Define keys                                                                 
(define-key *root-map* (kbd "c") "exec gnome-terminal")                        

; Emacs is commented out because I prefer to use                               
; it in the terminal.                                                          
;(define-key *root-map* (kbd "e") "exec emacs")  

(define-key *root-map* (kbd "f") "exec firefox")                               
(define-key *root-map* (kbd "v") "exec eog") ; Eye of Gnome                    
(define-key *root-map* (kbd "t") "exec thunderbird")                           
(define-key *root-map* (kbd "k") "exec keepassxc")                             
(define-key *root-map* (kbd "g") "exec gimp")                                  
(define-key *root-map* (kbd "r") "exec rstudio")                               
;; Functions                                                                   
(defun browse-url (url-string)                                                 
  "Browse url using WEB-BROWSER"                                               
  (check-type url-string string)                                               
  (run-shell-command (concat WEB-BROWSER "\"" url-string "\"")))

;; For connecting to emacs see:
;; http://www.kaashif.co.uk/2015/06/28/hacking-stumpwm-with-common-lisp/index.html