i3 4.8 featuring layout saving capabilities

There are going to be some exciting changes in the next version of i3. Version 4.8 will have a new feature of saving and restoring workspace layouts.

If you’d like to try it now, you can use a development branch of i3 git repository to build a package. Here is a SlackBuild script that can be used to build the ‘next’ version of i3. Please note that you need to specify the version as follows:

VERSION=next ./i3.SlackBuild

Without passing the version, the script will build the ‘master’ branch of i3, which is the latest stable version including all the bug fixes.

Before you can build i3-next, you need to install all the dependencies. Apart from the old ones (dmenu, libev and yajl), there are some new perl modules required. They are not runtime dependencies, but they are needed if you would like to utilise the new layout features.

New dependencies:
* perl-JSON-XS (available on SlackBuilds.org)
* perl-AnyEvent-Handle (script)
* perl-AnyEvent-I3 (script)

New layout features

The new layout features allow for a quick way of saving and restoring workspace layouts alongside with all the applications populating the placeholders. Below is a tutorial on how to use this feature.
The following is a layout we will be working on:

i3 layout
First, open and appropriately arrange required programs. In my cases it’s a number of xterm instances running various command line tools. To make it easier for a further identification of a window, I start each of them with a meaningful name, such as:

xterm -name topleft

I have 5 labels, each describing the position of a container: topleft, middleleft, bottomleft, topright, bottomright.

Once you’re happy with the layout, you need to save it in a file. The layout is going to be stored in a json format.

i3-save-tree --workspace 1 > /home/sycamorex/.i3/ws_1-generic.json

By default, the file is not yet ready to be used. First, you need to edit the file to ensure each window matches the criteria to be swallowed by the right container.

If you open the JSON file containing the layout, each section representing a window will contain a ‘swallows’ subsection that will help us identify each container

  "swallows": [
   // "class": "^XTerm$",
   // "instance": "^middleleft$",
   // "title": "^middleleft$"

  "swallows": [
   // "class": "^XTerm$",
   // "instance": "^bottomleft$",
   // "title": "^mc\\ \\[sycamorex\\@darkstar\\]\\:\\~$"

There are three things to observe here: by default, the class, instance, and title variables are commented out so we need to remove the comment tags. The title of the ‘middleleft’ window has not been captured. I would like it to be populated by ncmpcpp so I’d need to modify it so the section reads

 "swallows": [
    "class": "^XTerm$",
    "instance": "^middleleft$",
    "title": "^ncmpcpp$"

After the layout is loaded, the middleleft container can be populated by ncmpcpp in xterm with the following command:

xterm -name middleleft -e 'ncmpcpp'

The last thing to note is that although sometimes the title variable will get populated (like in the bottomleft section above), it may however need some cleaning up so that it reads:

 "swallows": [
    "class": "^XTerm$",
    "instance": "^bottomleft$",
    "title": "^mc$"

If any of the variables do not match a window properties, you can always check them with the xprop tool. Now that we have cleaned the JSON file (here you can see the entire file for the example above), we need to create a script that would load the layout and fill the placeholders with programs:


  # Load the layout
  i3-msg 'workspace 1; append_layout /home/sycamorex/.i3/ws_1-generic.json'
  # Swallow the programs into the containers
  xterm -name topleft -e 'ncmpcpp' &
  xterm -name middleleft -e 'irssi' &
  xterm -name bottomleft -e 'mc' &
  xterm -name topright &
  xterm -name bottomright -e 'emacs -nw'

The first command appends the layout to workspace number one and subsequently all the containers get populated with various CLI applications.

You can now bind the script to a key so that everything can be loaded in an instant. I have added the following to my ~/.i3/config:

bindsym XF86HomePage exec /home/sycamorex/.i3/i3-load-generic.sh

Alternatively you might want to load a layout on i3 startup. In that case, please add the following line to ~/.i3/config:

exec --no-startup-id "i3-msg 'workspace 1; append_layout /home/sycamorex/.i3/ws_1-config.json'"

You could also execute particular programs on i3 start.

exec --no-startup-id /usr/bin/xterm -name topleft -e 'ncmpcpp'

I’ve however chosen not to do it automatically as I do not need a particular layout everytime I start i3. Furthermore, I’ve created a few layouts depending on what I do or need: generic, web-devel, python-devel, etc. Each profile or layout is assigned a different key making it easy to quickly load it with one key.

Thank you, Michael, for adding it to i3.

Learn how to quickly switch between layouts.

3 Responses to i3 4.8 featuring layout saving capabilities


    Thanks for the article.

    My .json file is completely empty, apart from the one line;

    // vim:ts=4:sw=4:et

    What went wrong? All the dependencies are installed.

  2. admin

    Hi there,

    It would be useful if you posted the commands you issued. Having said that, it looks like your problem has been solved here: https://faq.i3wm.org/question/5169/i3-save-layout-doesnt-work-as-expected-json-file-is-empty/

  3. unam

    Thanks for your article.

    I was looking for this kind of help to really understand how it runs.

    Your article is very clear and simple instead of i3 doc for this kind of usage (btw, i3 doc is often helpful and clear too).

    See you !

Leave a Reply

Your email address will not be published. Required fields are marked *