Gentoo Wiki


Desktop environments

Lightweight desktop environments

Window managers

Compositing window managers




What is ion?

Homepage: Ion - An x11 Window manager

Ion is a tiling, tabbed window manager that keeps keyboard users in mind. It is a basic X11 setup with tabbed frames covering the screen. This allows for organization and ease for whatever you're working on.

Ion3 has been discontinued from the official portage repository due to license incompatibilities. Read more about this on the Gentoo Forums.

How to install Ion

a) Compile and install from tar ball

As ion-3 is not in portage easiest way is build from tar ball.

 - Download latest version from
 - emerge lua and gettext if needed
 - tar xvfz ion-3-*.tar.gz 
 - cd to ion-3-*
 - Edit ( change LUA_DIR to /usr )
 - make
 - sudo make install

I am not sure if this works well or not if u have emerged ion3 previously and have existing configs that needs to be reused etc.

b) Emerge ion3 after getting the overlay working

This may or may not work. One of the following needs to be true:

Something that may help is older versions of ion (which were under a different license) that are somewhat hard to find. Some old versions can be found at here

x11-wm/ion is still in the portage tree, just nothing newer (neither ion2 nor ion3), so this guide is how to install ion3.

So first we need layman and subversion.

Shell: Install layman
emerge -av layman subversion

Then you need to create a directory for your overlay(s):

Shell: Create layman's director
mkdir -p /usr/portage/local/layman/

You also need a description of the overlay in a xml file. I used ion-overlay.xml. You can use anything here, except for overlay.xml which gets used by layman.

File: /usr/portage/local/layman/ion-overlay.xml
<?xml version="1.0" ?>
      type = "svn"
      src  = ""
      contact = ""
      name = "ion-overlay">



In /etc/layman/layman.cfg, you need to tell layman about the overlay:

File: /etc/layman/layman.cfg
overlays  :

For paludis it can be something like this:

File: /etc/paludis/repositories/ion.conf
location = ${ROOT}/var/paludis/repositories/ion/
sync = svn+
master_repository = gentoo
format = ebuild
names_cache = /var/cache/paludis/names
write_cache = /var/cache/paludis/metadata

Next you need a make.conf file for your overlays, with just a PORTDIR_OVERLAY variable in it:

Shell: Sync up and Modify make.conf
echo "source /usr/portage/local/layman/make.conf" >> /etc/make.conf
echo "PORTDIR_OVERLAY=\"\"" > /usr/portage/local/layman/make.conf

Now you have to "fetch" the overlays from the distant internets...or just from hardrive and then add the overlay(s) that you want. This will download all the current ebuilds.

Shell: Add the overlay, then sync it
layman --fetch
layman -a ion-overlay

To update in the future you can run:

layman --sync ion-overlay

Incidentally eix-sync seems to at the very least pull in the current version of the overlays you have on your machine. No word yet on whether it calls sync as well.

Finally to install ion3 you need to do an

emerge -av ion3

If the install fails due to the files not being found you will have to find the tar.gz files for the version somewhere on the internet. One hint is that they should be held in the non-free debian repositories: just download the tar.gz for your version and your ready to go again.

c) Emerge ion (ion1)

ion is outdated, but easy way to test if you are into ion.

First emerge the window manager

emerge -av ion 

Configure and switch to ion3

In order to switch to your new window manager ion3 we need to edit your ~/.xinitrc file. If you dont have one in your home directory, you can create one, and it will still work when you use startx.

File: ~/.xinitrc
  exec ion3

Thats all there is to it. Global configuration files are located in the /etc/X11/ion3/ folder, but for most things you should probably edit the files in ~/.ion3. Especially useful is the ~/.ion3/cfg_bindings.lua file; this lets you change and add your own key bindings. There are also some cool themes that can be made. For example heres my theme, I found on the main webpage and made a few changes :)

File: /etc/X11/ion3/look_tiny.lua
 -- look_tiny.lua: an ion3 style for small mine :(
-- based on look_minimalist.lua

if not gr.select_engine("de") then return end


de.defstyle("*", {
    bar_inside_border = false,
    background_colour = "black",
    foreground_colour = "green",
    padding_colour = "black",
    padding_pixels = 0,
    highlight_pixels = 0,
    shadow_pixels = 0,
    border_style = "ridge",
    font = "-*-lucida-medium-r-normal-*-10-*-*-*-*-*-*-*",
    text_align = "left",
    transparent_background = false,

de.defstyle("frame", {
    based_on = "*",
    spacing = 2,

de.defstyle("frame-floating", {
    based_on = "frame",
    highlight_colour = "green",
    shadow_colour = "green",
    highlight_pixels = 1,
    shadow_pixels = 1,
    padding_pixels = 3,

de.defstyle("tabstyle", {
    based_on = "*",
    background_colour = "#222222",
    de.substyle("active-unselected", {
            padding_colour = "#353577",
            background_colour = "#000044",
    de.substyle("inactive-selected", {
            padding_colour = "#707070",
            background_colour = "#505050",
    de.substyle("active-selected", {
            padding_colour = "#5555cc",
            background_colour = "#223399",

de.defstyle("tab", {
    based_on = "tabstyle",
    spacing = 2,

de.defstyle("tab-menuentry", {
    based_on = "tabstyle",
    font = "-*-lucida-medium-r-normal-*-12-*-*-*-*-*-*-*",
    text_align = "left",

de.defstyle("tab-menuentry-big", {
    based_on = "tab-menuentry",
    font = "-*-lucida-medium-r-normal-*-24-*-*-*-*-*-*-*",

de.defstyle("input", {
    based_on = "*",
    padding_pixels = 1,
    font = "-*-lucida-medium-r-normal-*-14-*-*-*-*-*-*-*",
    de.substyle("*-cursor", {
        background_colour = "#00ff00",
        foreground_colour = "#000000",
    de.substyle("*-selection", {
        foreground_colour = "#5555cc",

de.defstyle("stdisp", {
    based_on = "tab",
    background_colour = "#000000",
    padding_colour = "#000000",
    de.substyle("important", { foreground_colour = "#ffff00", }),
    de.substyle("critical", { foreground_colour = "#ff0000", }),
    de.substyle("gray", { foreground_colour = "#505050", }),
    de.substyle("red", { foreground_colour = "#ff0000", }),
    de.substyle("green", { foreground_colour = "#00ff00", }),
    de.substyle("blue", { foreground_colour = "#0000ff", }),
    de.substyle("cyan", { foreground_colour = "#00ffff", }),
    de.substyle("magenta", { foreground_colour = "#ff00ff", }),
    de.substyle("yellow", { foreground_colour = "#ffff00", }),



I upgraded to 20061223 and now nothing works

The 20061223 version of ion3 made some major changes to ion3's architecture, so you may need to change your config files. It's probably best to move your existing ~/.ion3 directory to ~/.ion3.old and to make a new, empty ~/.ion3. Ion will use the defaults in /etc/X11/ion3 if it doesn't find the relevant files in ~/.ion3, so initially you shouldn't worry about copying anything into ~/.ion3 except for cfg_ion.lua, and that only to define ALTMETA. (Make sure to copy the cfg_ion.lua from /etc/X11/ion3, not from ~/.ion3.old, since you want to make sure you have the newer version.) Once you've got a working system, you can copy back files from ~/.ion3.old (or better yet, copy files from /etc/X11/ion3 and modify them based on your changes to the ~/.ion3.old files). Many bindings which formerly were in cfg_bindings.lua are now in cfg_ioncore.lua, so if something unexpected is happening, check that file. Also, some objects and properties have been renamed; check the ion3 function reference for specific cases. This should solve many of your basic problems.


Because ion is not really supported anymore, it may be wise to consider an alternative tiling window manager. Possibilities include:

Retrieved from ""

Last modified: Wed, 15 Oct 2008 01:48:00 +0000 Hits: 19,266