Documentation for i3 v4.23

One of i3’s goals is good documentation. The documents which you will find below will hopefully answer all your questions. If you have any corrections or suggestions please let us know!

For users

User’s Guide

Introduction and reference. Read this!

Code of Conduct

Outlines acceptable behavior within the i3 projects.

Layout saving/restoring

Explains how to save a layout and restore it in a new i3 session.


Interesting for users of the nVidia driver.

Debugging i3

Explains you how to enable debug logging.


Explains how to configure and customise i3status.

External workspace bars

About bar programs such as i3bar or dzen2.

i3 reference card

Might be useful to memorize i3’s shortcuts.

For developers

Hacking Howto

Helps you if you want to get into i3’s source code.

Debugging i3

Explains you how to enable debug logging.

Inter process communication (IPC interface)

Read this if you want to talk to i3 within your script.

i3 testsuite

Makes you able to read and write i3 testcases.

i3bar protocol

Documents the JSON based protocol which i3bar uses.

User-contributed articles

i3 buildbot setup(2012-09, by Michael)

Describes the buildbot setup that i3 used to use for automatic docs, compilation and debian packages before moving to Travis.

Lukáš Zapletal’s i3 configuration (2012-08, by Lukáš)

A detailed explanation of Lukáš’s configuration of i3 and related tools.

Swapping workspaces (2012-09, by Sagar)

Shows how Sagar uses i3’s IPC interface to swap workspaces between two outputs.

Using conky with i3bar (2012-11, by Gianrico)

Shows how to configure conky to generate JSON input for i3bar (with colors)!

Enhanced and extensible i3bar with py3status (2013-02, by Ultrabug)

Introduces py3status, a wrapper script for i3status which is easily extensible.

i3wm T-shirts(2013-12, by Stefan)

Where and how to order official i3 T-shirts.

Switch to workspaces on the current output(2014-08, by captnfab)

When switching workspaces, i3 sets focus to the output of the target workspace. With the script that is presented in this article, you always stay on the same output, and instead the workspace is moved.

User-contributed article: responsive, customizable and featureful status bar with luastatus and i3bar(2020-01, by shdown)

Describes the details of using the new status bar content generator, luastatus, with i3bar.