Gentoo Wiki


Please improve it in any way that you see fit, and remove this notice {{Cleanup}} from the article. For tips on cleaning and formatting see Cleanup process

Warning: This page is outdated. See Compiz Fusion for a more up to date guide

Eye Candy


Window Managers

X Configuration

Xgl/Compiz cube with 'in' setting
Xgl/Compiz cube with 'in' setting

Window sorting feature
Window sorting feature

Compiz Alt+Tab replacement
Compiz Alt+Tab replacement

Compiz is an OpenGL-based compositing and window-manager. Compiz is the original compositing window manager from Novell's XGL project. It is developed by David Reveman and community.



Compiz can be a nice luxury item on your desktop. It can provide smooth transition effects of windows many other tricks. While Compiz was once Gnome dependent, newer versions of Compiz can run on Gnome and KDE. A fork of Compiz called Beryl also provides compositing and window effects. Though Beryl and Compiz are reintegrating - See Compiz Fusion

Compiz's main differences from Beryl include;

Compiz Requirements

First be sure your video card is properly configured and that the drivers for it are set up correctly. If you need help about that, refer either:

Also Compiz requires Open-GL hardware acceleration ability to be added to the desktop. x11-7.1 (specifically xorg-server-1.2.0-r3) and later builds have AIGLX support built into them, but you will need more info on how to setup xorg.conf See more at either:

NOTE: you will only need to install one of the above to have a functional Compiz


Installation from Portage is the simplest but likely not the newest.


The version of Compiz does not require many dependencies.

You will need GIT to access the repository:

emerge dev-util/git

Next 'git' (har har) the Compiz version from

git clone git://

Next, follow the instructions contained within the INSTALL file in the compiz directory.

From Portage

It may be necessary to unmask compiz, as only the development version is in portage.

# echo x11-wm/compiz >> /etc/portage/package.keywords
# echo x11-apps/compiz-settings >> /etc/portage/package.keywords
# echo x11-plugins/compiz-extra >> /etc/portage/package.keywords

Then emerge compiz; compiz-{settings,extra} are optional.

# emerge compiz
# emerge compiz-settings compiz-extra

The packages compiz-settings and compiz-extra may not even build.

The tools provided by compiz-settings may not work on the newest versions of Compiz.

From xeffects Overlay

Information on setting up this overlay can be found in HOWTO Gentoo xeffects.

Be sure to use only the specific Compiz ebuilds from this overlay. Using SVN ebuilds of xorg-server and other vital parts will cause problems. Portage contains everything necessary except your custom Compiz ebuild.


The first step here is to configure Compiz and its plugins. If no plugins are specified, then you won't even get window decorations! (No minimize/maximize/close buttons, no resizing, no nothing, nada, niets, niente, res, nichts, rien, ничего, nic, kuch nahin, intet, nieko, shoonya, ingenting, nix, zilch, nimic, nenio, 何も, כלום, intet, nič, niks, ništa, az Ég adta világon ejalok никаких semmit!)

There are two ways of specifying plugins. You can specify everything on the command-line, or use a graphical configuration editor such as gconf-editor or gset-compiz. But you can't do both! If gconf is specified on the command-line, then Compiz ignores all other command-line plugins and grabs its plugin list from your gconf configuration instead.

So, if this is your first time running Xgl and you want to configure with a graphical tool, now is the time to do it, before you exit your X session.

At the very least, you need gconf and decoration. However, if you want to turn on all the fancy effects, you should also add wobbly, fade, switcher, move, resize, place, minimize, cube, rotate, zoom, and scale, in that order. You can more or less deduce the nature of what a plugin does by its name, so don't feel obligated to enable them all. It's likely that regardless of your taste in eye-candy, you'll want the move and resize plugins, so you have the ability to do those things.

Default: Using the Configuration Editor

If you use Gnome the Configuration Editor is pretty simple way to setup Compiz. You'll either find it in System Tools or you can use the commandline:


In the editor navigate to apps --> compiz --> general --> allscreens --> options and edit the active_plugins node on the right.

If the compiz entries do not appear in gconf-editor, these commands could possibly fix it:

 # export GCONF_CONFIG_SOURCE="xml:merged:/etc/gconf/gconf.xml.defaults"
 # gconftool-2 --makefile-install-rule /etc/gconf/schemas/compiz.schemas

Alternate: Using gconftool-2

gconftool-2 is a command-line tool to edit gconf settings in Gnome.

gconftool-2 -s /apps/compiz/general/allscreens/options/active_plugins "[gconf,decoration,wobbly,fade,minimize,cube,switcher,move,resize,place,rotate,zoom,scale]" -t list --list-type=string

Specify what plugins you want between the square brackets.

Alternate: Using compiz-settings

Compiz Settings has a nice GUI that lets you alter settings. Compiz Settings may not work with the newest versions of Compiz however.

emerge compiz-settings 

Resetting gconf Settings

If you have made an error, or plan to use a different version of Compiz then it may be best to erase your Compiz settings and start over.

gconftool-2 --recursive-unset /apps/compiz

Starting Compiz

The installation of Compiz puts a tiny script that works well for a number of users:



The following can be used as a script to start Compiz manually:

LD_LIBRARY_PATH=/usr/lib/opengl/xorg-x11/lib/ \
compiz --replace gconf &
gtk-window-decorator &

You should place this script in your path:

File: /usr/local/bin/compiz-decorator
compiz --replace gconf &
sleep 2
gtk-window-decorator --replace &

Change the permissions on /usr/local/bin/compiz-decorator to make it executable:

# chmod +x /usr/local/bin/compiz-decorator

Alternatively you can autostart Compiz and gtk-window-decorator on a per user basis by adding desktop entries into the respective gnome autostart directory. Create a plain text file named compiz.desktop in ~/.config/autostart/ and add

[Desktop Entry]
Name=No name
Exec=compiz --replace --loose-binding gconf

Also create gtk-window-decorator.desktop and add

[Desktop Entry]
Name=No name
Exec=gtk-window-decorator --replace

After these files are created Compiz can be started by logging off and back on. Compiz can be disabled by deleting the .desktop files, changing the X-GNOME-Autostart-enabled to false, or using the Sessions tool in Gnome Preferences ( System-> Preferences -> Sessions -> Startup Programs)

For KDE, Change windowmanager as follows:

File: /etc/env.d/99kde-env

Gnome's window manager can be defined in an environment variable. Modify:

File: /etc/env.d/99gnome-env

If you are using xfce4 edit the /etc/xdg/xfce4-session/xfce4-session.rc as following at the end of the file

File: /etc/xdg/xfce4-session/xfce4-session.rc
# This the default session launched by xfce4-session if the
# user hasn't saved any session yet or creates a new session.
[Failsafe Session]

At last update your environment

# env-update

Compiz Plugins

As stated above, compiz plugins can be specified as command line parameters to compiz when starting it, or with gconf (apps/compiz). It's a good idea to browse the settings for the plugins with gconf-editor (non-obvious/interesting settings listed below).

Plugins Loading Order

From the author:

There are currently two things with the plugin system in compiz that are a bit confusing.
1. Once you've loaded the gconf plugin, plugins specified on the command line will be ignored. gconf plugin will override them with the list of plugins stored in the gconf db.
2. Some plugins depend on other plugins and some plugins needs to be loaded before other plugins. The plugin loader will not do anything to try and resolve the order, if some plugin can't be loaded due to a dependency problem it will just be ignored.
The plan was to have some other program for configuration and loading of plugins and this program could figure out the order in which the plugins should be loaded. But maybe we should add some code to the plugin loader for this instead.
The current order in which the plugins should be loaded: gconf,decoration,wobbly,fade,minimize,cube,rotate,zoom,scale,move,resize,place,switcher

Plugins List

Raises the windows up off the desktop when rotating the cube or zooming. Currently in extras.
Adds animation effects to window actions. Revision 1162 from svn. Includes burn with smoke, mystical burn (multi coloured fire) and beam up effect. Currently in extras.
The bench plugin shows a fps benchmark on your screen. Currently in extras.
The border plugin allows you to assign a binding to toggle the window frame on and off. Currently in extras.
Brightness & Saturation
Allows adjustment of window brightness and saturation. Currently in extras.
Simple video capture plugin. Currently in extras.
Conditional Opacity Plugin. This allows you to have transparent backgrounds and opaque text in terminals. Thanks to moppsy for the porting of this plugin. Currently in extras.
Writes a dumpfile on crash and restarts an alternate window manager. Currently in extras.
Groups windows so they can be moved and resized together. Currently in extras.
Puts windows in specific positions. Currently in extras.
Show Desktop
Shows the desktop in an animated way. Version 1160 from Beryl svn, includes Corners. Currently in extras.
Different wallpaper on each cube face. Note - you need to kill kdesktop before the images will show. Currently in extras.
Provides the cube the virtual desktop is mapped upon. You can also configure svg slides on the top (as shown in the offical xgl presentation). This is (currently) a necessary prerequisite for rotate.
  • in: Places the visitor inside the cube (just test to see)
  • skydome: Whether to display a skydome image behind the cube as it rotates
  • skydome_image: Image to display behind the cube if skydome is enabled
  • svgs: List of svg images to be displayed on top of the cube; these can be cycled with the keys bound to the next_slide and prev_slide settings
Skydome can be successfully run on cards without modern shader support, contrary to many reports. Screenshot:
Enables Window Manager. Nevertheless you need to start a decorator! e.g `gnome-window-decorator` that is included with compiz.
Similar to miniwin. Displays a small live preview of all windows (minimized and normal) at the bottom of the screen. Stacks perviews of windows belonging to the same program on top of one another. Highly experimental and unsupported.
Makes windows/tooltips/menus fade in/out when opened/closed.
  • fade_speed: How fast the fade effect is
Enables quartz like minimizing effect.
  • speed: How fast the minimizing effect is
This is an experimental plugin. It allows the user to create an icon of a window, currently being called a mindow, that shows a picture of the main window and can be clicked on to return the main window. It is a possible replacement for the minimize funtionality.
Allows you to configure a key/mouse-button combo to move a window anywhere within its canvas.
  • constrain_y: Prevents the window from being moved above the top of the screen
  • initiate: Keybinding to initiate move effect; Alt+drag by default
  • opacity: Decrease window opacity by this percentage while moving
  • terminate: Keybinding to release window
Inverts the colour of a selected window. Super + n by default in new versions.
Places new windows in logical positions that will usually not overlap with other windows or toolbars.
Allows you to configure a key/mouse-button combo to resize a window anywhere within its canvas. A version in extras is rewritten by the Beryl project.
Enables 3d desktop rotating via keyboard+mouse shortcuts.
  • flip_time: How long the rotation effect takes
  • initiate: Keybinding for manual rotation, Ctrl + Alt + Drag by default
  • rotate_left: Keybinding to flip one screen left, Ctrl + Alt + Left arrow by default
  • rotate_left_window: Same as rotate_left, but drags the active window with it to the next desktop
  • rotate_right: Keybinding to flip one screen right, Ctrl + Alt + Right arrow by default
  • rotate_right_window: Same as rotate_right, but drags the active window with it to the next desktop
  • snap_top: Allows to snap to the top of the cube while manually rotating, instead of just snapping to the nearest desktop
Exposé-like window-switcher.
  • initiate: Keybinding to activate switcher effect
  • next_window: Keybinding to select the next window
  • opacity: Percentage by which to reduce the opacity of non-active windows
  • sloppy_focus: mouse-over focus
  • spacing: Space to maintain between windows
  • terminate: Keybinding to end switcher effect
Sets default settings of applications.
settings syntax:
Type can be any of the following:
  • w: Window type: Can be Dock, Toolbar, Menu, Utility, Splash, Normal, Dialog, ModalDialog or Unknown.
  • c: Window class: The same as the window executeable, only with first character in upper case.
  • t: Window title: The same as the window title
  • p: Executeable path name: The same name as the executeable name in $PATH.
  • Opacity: w:Normal:95 gives all normal apps a slight transparency that looks very neat.
  • Viewport: p:opera:3 makes Opera run in viewport/virtual desktop number 3
  • Viewport: c:Eclipse:2 makes Eclipse-sdk run in viewport/virtual desktop 2. (use class instead of path because you launch eclipse with the eclipse-3.x wrapper, which in return runs the eclipse binary that is not located in path)
Alt+Tab Application switcher replacement, with live window previews
  • initiate: Keybinding to start switcher, Alt + Tab by default
  • initiate_all: Keybinding to start switcher with windows from all desktops, Ctrl + Alt + Tab by default
Changes brightness, saturation and opacity of your windows depending on how long you have not used them.
This plugin is currently quite unstable. Reports say it uses intense CPU resources, and crashes X. Use at your own risk. Needs (definitely; not probably) shader support to be seen.
Enables special layer for widget windows... but no idea how it works.
edit (04.08.2006): I found a german description here:
Makes windows wobble like jelly when moved or resized.
  • focus_effect (None, Shiver): Effect when a window gets focus. This might interact badly with scale with sloppy_focus set.
  • map_effect (None, Shiver): Effect when a window gets created
  • friction, spring_k: Affect together the wobbliness
  • grid_resolution, min_grid_size: The resolution of the grid which is wobbled
  • snap (shortcut): Wobbly snapping while moving windows
Enables zooming in and around desktop.
  • filter_linear: Apply a linear interpolation when scaling, to reduce appearance of pixels

Using Plugins

So you've suffered long enough trying to get XGL installed, now how do you use it? Here are the various key combinations for various plugins:

Switch windows = Alt + Tab

Arrange and View All Windows = F12 turns on or off; clicking a window will zoom it to the front

Arrange and View All Windows (gnome-window-decorator, not cgwd) = Ctrl + Shift + Up turns on; clicking a window will zoom it to the front, or select window using arrows and release Ctrl + Shift

Arrange and View Windows of the Same Application = F11 turns on or off; clicking a window will zoom it to the front

Slow Motion = Shift + F10

Switch desktops on cube = Ctrl + Alt + Left/Right Arrow

Switch desktops on cube - with active window following = Ctrl + Shift + Alt + Left/Right Arrow

Flatten Cube - Ctrl + Alt + Page Down, then Left/Right Arrows to switch desktops

Flatten Cube (gnome-window-decorator, not cgwd) - Ctrl + Alt + Down, then Left/Right Arrows to switch desktops

Rotate desktop cube = Ctrl + Alt + Left-click on wallpaper and drag

Display svg picture on top of cube = modify gconf db,add svg files to /apps/compiz/plugins/cube/screen0/options/svgs (restart needed)

Make window translucent/opaque (built-in) = Alt + mouse wheel up/down

Make window translucent/opaque (with the opacity plugin) = Ctrl + Shift + Scroll, or right-click the window's title bar and select Opacity (seems to be absent in current compiz cvs.)

Zoom-in once = Super-key right-click

Zoom-in manually = Super-key + wheel mouse up

Zoom-out manually = Super-key + wheel mouse down

Move window = Alt + left-click

Snap Move window (will stick to borders) = Shift during move (either by Alt + left-click or by title bar)

Resize window = Alt + right-click

Resize window (gnome-window-decorator, not cgwd) = Alt + middle-click

Water Effect = Ctrl + Super-key (I have to press the Ctrl key first) - (depends on water plugin)

Rain = Shift + F9 (Requires the water plugin)

Note: Super-key is the same as the windows key

You can change all of these using gconf-editor (Might be necessary since the windows key is reported not to work with xgl on some systems).

Warning: The key combinations interact! If you bind something to <Alt><Ctrl>Button4 and to <Ctrl>Button4 both will be activated if you use the first!
Warning: The key combinations are also passed-through to apps below the cursor.

See also Compiz/Tips and Tricks

Using Command-Line

As mentioned, it is possible to run compiz with command line switches, and ignore any settings made with gconf-editor. The syntax is as follows:

compiz [options] ${space delimited plugin-lists}

Available options:
  --display DISPLAY
  --bg-image PNG
  --window-image PNG
  --refresh-rate RATE

For example:

compiz --replace miniwin decoration transset wobbly fade minimize cube rotate zoom scale move resize place switcher trailfocus water &


The normal Desktop Preview & Pager Applet doesn't work very well with Compiz. But there is a Version at (kicker-compiz) that works (

Known issues

Switcher plugin stick in the middle of the screen

To deal with that issue, you have to remove Splash in the window_types key of the fade plugin options.

Resize plugin is very slow

If resizing windows is very slow, try this: Launch gconf-editor and there goto apps->compiz->plugins->resize->allscreens. Make sure stretch_texture is checked. (buggy?)

SDL is slow

To get SDL Applications back to their old speed try loading them like this:


compiz: No sync extension

Add this to /etc/X11/xorg.conf

File: /etc/X11/xorg.conf
Section "Module"
	SubSection	"extmod"
		Option	"omit xfree86-dga"

This is suposed to fix this error.



Last modified: Sun, 07 Sep 2008 06:46:00 +0000 Hits: 136,811