Skip to content
aykaramba edited this page Jun 19, 2022 · 22 revisions
Clone this wiki locally

This is the stumpwm FAQ.

If you have a question but no answer, put it up anyway and hopefully someone will answer it.

You can ask for more answers on our:

IRC channel: #stumpwm on (

Mailing list:


How Do I build Stumpwm?

Consult StumpWM README.

How Do I change the prefix key?

Changing the prefix key is done with set-prefix-key.

If you would like to change it to the very nice C-z try (set-prefix-key (kbd "C-z"))

You can also change it interactively with the escape command: C-t ; escape C-z

How Do I make my windows key the prefix key?

As far as I (LqR) know, the left windows key has #115 and the right one is 117. The Windows key has also been known to be #133.If it doesn't work for you, you might want to run xev to find the number of your windows key.

First, you need to map your windows key to a X key, for example F20. Do xmodmap -e "keycode 115 = F20". You may need to clear it first with xmodmap -e "clear mod5".

If you are going to use this setup permanently, you might want to add this mapping statically by adding a line with the above mentioned command in your .xinitrc (before StumpWM!), or by adding xmodmap $HOME/.xmodmaprc (also before stumpwm) to your .xinitrc and adding keycode 115 = F20 and any other xmodmap commands you wish to your .xmodmaprc

Then, set StumpWM to use the "F20" key (== your left windows key) by adding (set-prefix-key (kbd "F20")) to your .stumpwmrc. Also, remember to do (in-package :stumpwm) in your rc file, or else StumpWM won't find the function kbd! Alternatively you can use stumpwm:kbd instead of kbd and omit (in-package :stumpwm).

Update: On more recent versions of distributions based on Gnome, such as Debian and Ubuntu, the windows key has already been mapped to super, which means it can be used in key bindings using the lower case 's' letter. For example, to make the windows key the prefix key, you can do

(set-prefix-key (kbd "s-t"))

to change the prefix from control-t to super-t i.e. windows key plus t

How do I make keybindings that don't use the prefix key?

Use the *top-map* rather than the *root-map*. For example,

(define-key *top-map* (kbd "M-1") "gselect 1")

Now, pressing Meta-1 (without the prefix key) will call gselect 1.

Does StumpWM support having dual-head/multiple monitor setups?

StumpWM supports multiple monitors, but they must be configured by X11. StumpWM does not provide any logic for attaching/resizing monitors. StumpWM will respond to RandR events and repopulate the heads (StumpWM's concept of a space for placing windows) as needed. Occasionally RandR events will get intercepted by another program (ie unity-settings-daemon on recent (> 13.10) version of ubuntu). In this case you can force the refresh of heads by running the command refresh-heads. (This applies to stumpwm 0.9.9 and later).

Utilities that can be useful for managing multiple displays include:

If your running StumpWM within a desktop environment, you can probably use the external monitor application that is native to the desktop environment.

My multi screen setup is broken; instead of having a separate frame on each monitor I have a single frame that spans both of them

Install the xdpyinfo utility; it's used to detect the heads - if it's missing StumpWM will assume that there is only one head, hence there will be only one frame instead of multiple frames as you'd expect from multiple monitors.

How do I make the caps lock key more useful?

You can remap it to be another Ctrl key in a manner similar to the above. Add remove lock = Caps_Lock add control = Caps_Lock to your ~/.xmodmaprc

man xmodmap generally provides other interesting examples as well.

Does StumpWM have a manual?

Yes, the texinfo manual comes with StumpWM and is called stumpwm.texi. To build an info file out of it run:

sh $ makeinfo stumpwm.texi

What lisps does StumpWM currently work on? Which one should I choose?

Right now it runs on SBCL. Previously it ran on others, but they are no longer supported.

See Compiling SBCL.

I'm coming from ratpoison and I want to convert my rc file to work with StumpWM. Where do I start?

Yeah, this is one of the reasons I'm too afraid to migrate any time soon.

I'm getting a gray or black border around some windows but not others. Why?

Some windows provide a resize increment hint that asks the window manager to ensure it's size is always a multiple of these hints. For instance, Xterms have a resize increment hint based on the size of the font they use. This way they resize by columns and rows.

Why is the mouse pointer an X and how do I change it?

That's the default pointer icon for X windows. To change it to an arrow:

sh $ xsetroot -cursor_name left_ptr

Or put this in your rc file:

(stumpwm:run-shell-command "xsetroot -cursor_name left_ptr")

Why is the stumpwm binary so big?

When you build an image using sbcl, it's about 32M. For window managers that's pretty big. The reason is because all of sbcl is dumped with stumpwm. Remember, stumpwm runs on a full common lisp distribution which depending on who you ask is jam packed with features and functionality or bloated. Dumping an image, as stumpwm does, is the equivalent of statically linking all the dependency libraries in a C program.

How do I pull windows with numbers higher than 9?

Either do C-t ; pull RET and it will prompt you for a window number, or bind just "pull" to a key and it will prompt you for a window number.

How do I make StumpWM recognize modifiers like ISO_Level3_Shift (aka AltGr)?

Although this does not fix the problem, this workaround in ~/.stumpwmrc works:

(defparameter *shift-map* (make-sparse-keymap)) (define-key *root-map*
(kbd "ISO_Level3_Shift") '*shift-map*)

;; To map the help on C-t AltGr-q: (define-key *shift-map* (kbd "q") "help")

Can I use a panel and still use the built in mode-line?

For example have the mode-line at the top of the screen and have a panel at the bottom for using applications like NetworkManager.

Can I use a panel other than the built in mode-line?

Yes, using StumpWM from the Git repository. KDE's kicker and Gnome's gnome-panel work fine, as should any other panel application that remembers to set its dock type before calling XMapWindow.

To use KDE's kicker

  1. For stumpwm integration you will only have to disable KDE's control of the Desktops as described in the link.

  2. Then create the also described in the link. Hint: to get the location of your stumpwm you can execute the following in Emacs: With the point (your cursor) in front of the export KDEWM= C-u M-! which stumpwm

  3. Logout of KDE and log back in. Upon logging in the Kicker will startup before stumpwm is finished loading. Just wait a few seconds and you will be greeted by the stumpwm welcome message. Stumpwm will now use kicker as the mode-line; so as you create groups they will show up in the pager(if you hover your cursor over the pager it will display the name of the group) if you have it on. Applications will also appear in the Task Manager if you have it on as well.

Note: If you want to make changes to any of the panels I found that it is

  • easiest to create a floating group for that. gnew-float settings

  • If you move the panel around I have noticed that it will cause things to freeze up and glitch for a few seconds upto a minute after making the change but after that everything goes back to normal.

When compiling I am getting errors about "clx-system::SB-BSD-SOCKETS"


I am using SBCL, and I have previously been able to build StumpWM just fine from GIT, only now I can't anymore, because make throws me "Error during processing of --eval option (LOAD #P"./make-image.lisp"):

component CLX-SYSTEM::SB-BSD-SOCKETS not found, required by #<SYSTEM "clx" {10025F7061}>".

I have both cl-clx-0.7.3 and cl-ppcre-1.2.16.

I mentioned this question in #stumpwm, it seems someone has had this error about a year ago, the cause being a broken SBCL from FreeBSD ports. And I'm not sure but "CLX-SYSTEM::SB-BSD-SOCKETS" seems weird to me (it may not be). Also, there's a mailing list you may wish to ask this question on if you still have a problem here:

I'll toy around with SBCL a bit and see what I find. Thanks anyway.

I use dwm/ion/wmii, why should I switch to Stumpwm?

Well, dwm requires you to edit the source code and recompile, then restart, to configure it. Not really my idea of a good time. With StumpWM, you can edit your ~/.stumpwmrc and evaluate it right then and there with stumpwm-mode.el, send commands from your shell of choice using the stumpish command, or press C-t : to send lisp commands straight to the lisp running StumpWM. You can completely (or slightly, if you prefer) alter its behavior ... while it's running.

How do I close a window (read:the equivalent of pressing the x icon in a

window manager with borders) in stump?

C-t k

How do I make keypresses show up in a message window as I press them?

Add the following code to your .stumpwmrc file (note: this will pause every command for 0.5 seconds, making your stumpwm slightly slower):

;; Code by Male Display the keysequence in progress
(defun key-press-hook (key key-seq cmd)
  (declare (ignore key))
  (unless (eq *top-map* *resize-map*)
    (let ((*message-window-gravity* :bottom-right))
      (message-no-timeout "Key sequence: ~A"
               (print-key-seq (reverse key-seq))))
    (when (stringp cmd) ;; Give 'em time to read it.
        (sleep 0.5))))

(defmacro replace-hook (hook fn)
  `(remove-hook ,hook ,fn)
  `(add-hook ,hook ,fn))

(replace-hook *key-press-hook* 'key-press-hook)

(defmacro replace-hook (hook fn) (remove-hook ,hook ,fn) (add-hook ,hook ,fn))

(replace-hook key-press-hook 'key-press-hook)

I'm trying to use sprev/snext in my xinerama setup to switch heads, but

nothing happens

snext/sprev only work for non-xinerama multi-head set ups. When Xinerama is enabled a head is just a frame, so use the frame commands to switch heads.

I'm on gentoo and stumpwm fails to start. It produces the error: There is

no applicable method for the generic function #<STANDARD-GENERIC-FUNCTION STUMPWM::SCREEN-MESSAGE-CC (1)> when called with arguments (NIL).

You're missing a font package that StumpWM needs to run.

StumpWM's default font, "9x15bold" is part of media-fonts/font-misc-misc. This package used to be a dependency of x11-base/xorg-server, but since version 1.5, it has to be emerged explicitly.

The default Ctrl-T hotkey doesn't work with OpenOffice!

Start OpenOffice with the -K or --headless option.

Component 'stumpwm' not found

Create source repository config for ASDF, e.g: ~/.config/common-lisp/source-registry.conf.d/my-asdf.conf with path to stumpwm directory like: (:tree "~/build/stumpwm/")

My mouse wheel doesn't work with gtk3 applications

Add the following to your .xinitrc: sh export GDK_CORE_DEVICE_EVENTS=1 If you don't use a .xsession or a .xinitrc, then you must set this somewhere upstream of stumpwm.

Alternatively, so long as you don't want to bind any stumpwm commands to the mouse wheel, add a when (/= i 4 5) to xwin-grab-buttons. This is particularly useful for laptops so that you still get full smooth scrolling on a touchpad.

How to connect to StumpWM with SLIME ?

This blog post will help you to get started.

StumpWM crashes after several hours due to a memory leak

This isn't an issue with StumpWM specifically, but rather with rendering TTF fonts. Switching to a bitmap font should fix the issue. The application xfontsel can be used to generate X Logical Font Description string. The relevant github issues are #474 and #592.