Column Window Management for Emacs

This page is about cwm-mode, a “column window management” minor mode for GNU Emacs. In this mode windows can be managed within a frame in a column-like layout—very much like in WMII and i3 window managers. Here, column is a set of windows having the same width and lined vertically on top of each other:

      |   w1   |   w4   |
      +--------+        |
      |   w2   +--------+
      +--------+   w5   |
      |   w3   |        |
        col 1    col 2

The number of columns is limited only by frame width. Windows can be moved up and down within columns, and to left and right between columns. Columns are created and deleted automatically as needed. Examples:

      +--------+--------+      	       +--------+--------+
      |   w1   |   w4   |      	       |   w2   |   w4   |
      +--------+        |      =>      +--------+        |
      |   w2   +--------+    	       |   w1   +--------+
      +--------+   w5   |  swap w1-w2  +--------+   w5   |
      |   w3   |        |	       |   w3   |        |
      +--------+--------+	       +--------+--------+
        col 1    col 2 	 	         col 1    col 2

      +--------+--------+      	       +--------+--------+
      |   w1   |   w4   |      	       |   w2   |   w1   |
      +--------+        |      =>      |        +--------+
      |   w2   +--------+    	       +--------+   w4   |
      +--------+   w5   |  move w1 to  |   w3   +--------+
      |   w3   |        |  the right   |        |   w5   |
      +--------+--------+	       +--------+--------+
        col 1    col 2 	       	         col 1    col 2

      +--------+--------+      	       +-----+-----+-----+
      |   w1   |   w4   |      	       |     | w2  | w4	 |
      +--------+        |      =>      |     | 	   |   	 |
      |   w2   +--------+    	       | w1  +-----+-----+
      +--------+   w5   |  move w1 to  |     | w3  | w5	 |
      |   w3   |        |   the left   |     |	   |   	 |
      +--------+--------+	       +-----+-----+-----+
        col 1    col 2 	 	        col 1 col 2 col 3

A column can be stacked by maximizing one of its window and minimizing others (this is basically a “poor man’s tabbed interface”):

      +-------+          +-------+
      |  w1   |          |       |
      |       |          |       |
      +-------+          |  w1   |
      |  w2   |          |       |
      |       |          |       |
      +-------+    =>    |       |
      |  w3   |          +-------+
      |       |  stack   |  w2   |
      +-------+          +-------+
      |  w4   |          |  w3   |
      |       |          +-------+
      +-------+          |  w4   |
      |  w5   |          +-------+
      |       |          |  w5   |
      +-------+          +-------+

Within stacked columns minimized windows have window-min-height lines, and the maximized window gets the remaining space.

Installation and Usage

Source code: cwm-mode.el. The latest version is 0.3.1. Please see the Change Log for details. Latest developments, if any, may be available at

Put the source file into your load-path and load it into Emacs. If you don’t know how to do that, see the Emacs manual for information about basic Emacs configuration. After loading the library, you can use cwm-mode function to toggle the mode on and off. GNU Emacs version 22 or later is required. Note that mode behavior can vary a bit between different Emacs versions due to internal differences.

I have tried to make this mode self-documenting. For a general overview see the documentation of cwm-mode (type C-h f cwm-mode RET). Each function and variable has also a documentation string which describes that function or variable in detail. Documentation strings are accessible with the standard C-h f function RET or C-h v variable RET key sequences. You can also use Emacs customization interface to customize cwm-mode: look for cwm group under Convenience and Windows groups.

Most interactive functions have default key bindings with prefix C-c ^. Type C-c ^ C-h to display them. Note that cwm-windmove-... functions are intended to replace the standard Emacs windmove-... functions. If you use the default windmove key bindings, you probably want to override them with their cwm-counterparts. For example, I use the following bindings:

Key Function
s-0 cwm-delete-window
s-1 cwm-delete-other-windows
s-2 cwm-split-window
s-3 cwm-split-column
S-<down> cwm-windmove-down
S-<left> cwm-windmove-left
S-<right> cwm-windmove-right
S-<up> cwm-windmove-up
S-s-<down> cwm-move-window-down
S-s-<left> cwm-move-window-left
S-s-<right> cwm-move-window-right
S-s-<up> cwm-move-window-up
S-s-<return> cwm-toggle-stacked

Here s- is the prefix for <SUPER> key.


This mode has (at least) the following glitches:

  • For Emacs, all minimized windows are regular windows despite their small size. This means that Emacs may choose minimized windows to display buffers, which is often undesirable. To prevent such situations you can add functions cwm-maximize-window-maybe and cwm-fit-window-maybe to suitable hooks, such as next-error-hook. Another workaround (for Emacsen older than version 24.3) is to override display-buffer-function with cwm-display-buffer; there exists a separate function cwm-toggle-display-buffer for doing that. See the help for information on what these functions do.
  • Stacked columns break if their enclosing frame is resized.
  • Overall, column stacking is kludgy. It might be better to use a dedicated tab bar mode instead. Emacs 27 has tab-bar-mode built in.
  • In Emacs versions older than 24.1, splitting an existing column with more than one window requires a temporary deletion of that column. During the restoration of the column some window properties (such as height) are lost. See cwm-move-window for details.

The primary reason for these deficiencies is that cwm-mode is stateless: it does not maintain any information about windows, columns, and the like. It calculates all information about the layout, such as the selected window’s column, on demand instead. This is a deliberate choice. Besides simplifying the code, it keeps the mode compatible with frame and window registers, winner-mode, revive+, and whatever other extensions dealing with windows, frames or sessions there might be in use. Furthermore, you are not restricted to column-based layouts. The layout-modifying functions try to cope with arbitrary layouts, but they can (and likely will) fail.


Copyright 2009, 2010, 2013, 2020 Petteri Hintsanen

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.


Author: Petteri Hintsanen


Created: 2020-08-19 ke 21:49