Gentoo Wiki


Eye Candy


Window Managers

X Configuration




Compiz Fusion, the reunification of Compiz and the Beryl fork, is a set of plugins and add-ons for Compiz, an OpenGL window and compositing manager. It has reached its first stable version: 0.6.0. Version 0.7.6 can be found on desktop-effects overlay. To use overlays in gentoo use this guide. Live ebuilds from git are numbered 9999.


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

Also, Compiz requires OpenGL 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 Use XGL only as a last resource as the latest ATI binary drivers already include experimental support for AIGLX. See more at either:



You need to add xcb to your global use flags and then recompile mesa and libX11. That will give you a xcb enabled X11. Most users will want to recompile libX11 FIRST, as recompiling mesa first may result in errors (specifically, libX11 compiled with 'xcb' is REQUIRED for mesa to compile with 'xcb').

Package List

Add the following lines to /etc/portage/package.keywords:


Emerging Cairo

Cairo needs to be built with the "glitz" and "svg" use flags. If it isn't already add "x11-libs/cairo glitz svg" to /etc/portage/package.use

echo "x11-libs/cairo glitz svg" >> /etc/portage/package.use

Now you can emerge cairo

emerge -1av cairo


Now you can emerge compiz-fusion:

emerge -av compiz-fusion

If the emerge fails, it may help to compile in a specific order:

emerge -v1a compiz compiz-bcop emerald libcompizconfig compiz-fusion-plugins-main compiz-fusion-plugins-extra compiz-fusion-plugins-unsupported compizconfig-backend-kconfig compizconfig-backend-gconf compizconfig-python emerald-themes ccsm compiz-fusion

If you have a KDE4 and it fails because of a kdecoration_p.h problem set USE Flag -kde.

nano /etc/portage/package.use
# Add following line
>=x11-wm/compiz-0.6.2-r1 -kde

now do the second emerge command

If compiling of compiz-fusion fails because of a "dbus/dbus.h: No such file or directory" error, emerge this:

emerge -v1a dbus-glib

compiz-fusion seems to need x11-proto/damageproto (at least for me it did), yet it doesn't seem to be a dependency. So go catch it first, in case you need it:

emerge -av x11-proto/damageproto

Starting Compiz Fusion


To start compiz-fusion, type compiz-start in terminal.


If it doesn't work for your system, try copying the script from /usr/bin to /usr/local/bin and change the COMPIZ_OPTIONS line to

COMPIZ_OPTIONS="--replace ccp --sm-disable"

or just try running the following once inside X:

compiz --replace ccp --loose-binding

ccp is the compiz configuration plugin. It reads your configuration settings (as set by ccsm) and applies them to compiz. It may be necessary to open the CompizConfig Settings Manager (run ccsm), click on 'Window Decoration', and then provide a decorator in the 'Command' field; use something like:

emerald --replace


gtk-window-decorator --replace

or, for kde users,

kde-window-decorator --replace

Furthermore, AIGLX users should make sure to define LIBGL_ALWAYS_INDIRECT=1:

compiz --replace ccp

or simply:

LIBGL_ALWAYS_INDIRECT=1 compiz --replace ccp

Using xinitrc.d

create a script called xy-compiz where xy is any decimal number that specifies the start order. (As in /etc/env.d/ or /etc/udev/rules.d/)
compiz-start &
sleep 2
compiz --replace ccp emerald &

Then chmod +x the file and compiz will start each time you start an X session.

Using tray icon

(At the moment (Sep 19 2008) there are no ebuilds for fusion-icon. Don't know if this is temporary or not )

You can use the x11-apps/fusion-icon to manage the effects. Fusion-icon is located on desktop-xeffects overlay.

If you want to do this you need to unmask it first ( it is masked by missing keyword ) so

nano /etc/portage/package.keywords

and add

x11-apps/fusion-icon **

Then just do

emerge fusion-icon

Starting Compiz Fusion with KDE

This can be done two very simple ways. The first and easy way is to make a soft link.

cd /home/$USER/.kde/Autostart
ln -s /usr/bin/compiz-start compiz-fusion

or (preferred) you can make your own init.

File: /home/$USER/.kde/Autostart/compiz-fusion

you can either place the run-time commands here or within the /usr/bin script, up to you. then you have to make it executable

chmod +x /home/$USER/.kde/Autostart/compiz-fusion

Next you must start CCSM so go to KDE: Applications - > Preferences - > CompizConfig Settings Manager (or try: KDE Menu -> Settings -> CompizConfig Settings Manager) and select options. In the box labeled 'command' enter:

kde-window-decorator --replace

what that is doing is kicking on the kde window decorator in case the init script /usr/bin/compiz-start doesnt figure out that you are running kde...supposedly. i get kde to start a handful of times fine and then i lose the titlebars, second installation.


You can configure your Compiz Fusion installation with the CompizConfig Settings Manager:

Gnome: System - > Preferences - > CompizConfig Settings Manager

KDE: Applications - > Settings - > CompizConfig Settings Manager

XFCE: Xfce Menu - > Settings -> CompizConfig Settings Manager

or by running this command:

# ccsm

Many thanks to ...

Many thanks to Starise from !!! He wrote the manual in Italian

And many thanks to Google Translation Service !!!

Tools and Tips

Feel free to amend this wiki with your patches, tips or scripts. Bugs or help requests should be posted to the discussion and bugs tab at the top of the page.

Starting compiz after startingup xfce using xfce-sessions

Create a script like the one below and save it in your $HOME folder. Then, autostart it using Autostarted applications module. It might also help if you don't save any of the xfce-sessions (and delete the ones you find under ~/.config/xfce4-session/).

File: start-compiz

# Uncomment the following two lines if you have a graphics card that uses i915/intel module.
# export INTEL_BATCH=1
compiz --replace --sm-disable ccp&
emerald --replace


I made a patch I run every time after I updated compiz (own script) to make sure I get compiz with the ccp --sm-disable options.

File: compiz.patch
 --- /usr/bin/compiz-start       2007-07-03 12:09:05.000000000 +0200
 +++ /usr/bin/compiz-start       2007-07-03 15:50:29.000000000 +0200
 @@ -30,12 +30,5 @@
         export LIBGL_ALWAYS_INDIRECT=1
 -if [ ! -z $KDE_FULL_SESSION ] && [ -x /usr/bin/kde-window-decorator ]; then
 -       echo Using KDE decorator
 -       kde-window-decorator --replace &
 -       echo Using GTK decorator
 -       gtk-window-decorator --replace &
 -compiz $COMPIZ_OPTIONS gconf move resize minimize place decoration wobbly fade cube rotate scale switcher zoom dbus
 +compiz --replace ccp --sm-disable &
 +emerald --replace &

Use it by running patch -p0 < compiz.patch

XCB workaround

In order to avoid problems in java and various problem that are arisen by xcb you should build xcb and libxcb with -DNDEBUG flag. Simply add CFLAGS="${CFLAGS} -DNDEBUG" to /etc/portage/env/x11-libs/libxcb and /etc/portage/env/x11-misc/xcb:

File: /etc/portage/env/x11-libs/libxcb and /etc/portage/env/x11-misc/xcb

For more details check (thanks Guenther Brunthaler for this tip)

If you use Paludis you could add

case "${PN}" in

         export CFLAGS="${CFLAGS} -DNDEBUG"

to /etc/paludis/bashrc
Patch java for when you didn't do the above

You can also leave xcb there and patch java with

locate|grep "/opt/sun-j.*/lib/i386/.*"|xargs sed -i 's/XINERAMA/FAKEEXTN/g'

Bash Script Updater

Here's a bash script to update Compiz-Fusion. (The order of items to install is good.)

# Horrible script by HTS 
# Enhanced by Dominicus 2007-08-30, irc://, #compiz-fusion channel

# Script: ""

# Name the script "", place it in "/usr/bin", and make it executable.
# Note, this script is for Gentoo Linux, and requires Layman with the desktop-effects overlay.

compiz_git_packages="compiz \
compiz-bcop \
libcompizconfig \
compiz-fusion-plugins-main \
compiz-fusion-plugins-unsupported \
compiz-fusion-plugins-extra \
compizconfig-backend-kconfig \
compizconfig-python \
compizconfig-backend-gconf \
ccsm \
fusion-icon \
emerald \
emerald-themes \

# blocked due to no longer being included in the "compiz-fusion" meta package.
#compiz-fusion-plugins-gears \
#compiz-fusion-plugins-shift \
#compiz-plugins-screensaver \

update_overlay() { 
	layman -s desktop-effects

case "$1" in 
                echo -e "Updating desktop-effects overlay" 
                echo -e "Unmerging the currently installed packages (if any)" 
                emerge -C ${compiz_git_packages} 
                echo -e "Emerging packages" 
                echo -e "  ...  You will be prompted, please wait ..." 
                emerge --oneshot --ask --verbose ${compiz_git_packages}

                echo "Making binary package backups of currently emerged compiz-fusion packages." 
                quickpkg ${compiz_git_packages} 

                echo "Reverting to the most recent binary backups of the compiz-fusion git packages." 
                echo -e "  ...  You will be prompted, please wait ..." 
                emerge --oneshot --ask --verbose --usepkgonly  ${compiz_git_packages} 

                echo "Cleaning all files downloaded from git." 
                rm -rf /usr/portage/distfiles/git-src/* 

                echo "Uninstalling the emerged version of Compiz-Fusion."
                emerge -C ${compiz_git_packages} 
                echo -e "`basename ${0}`: Compiz-Fusion installation tool for Gentoo Linux" 
                echo -e "The desktop-effects overlay (available via layman) is required to use this script." 
                echo -e ""
                echo -e "Usage: `basename ${0}` < backup | emerge | purge | remove | revert >"
                echo -e ""
                echo -e "  backup     ->  Make binary packages out of the currently"
		echo -e "                 emerged compiz-fusion packages." 
                echo -e "                 Example: \"`basename ${0}` backup\""
                echo -e ""
                echo -e "  emerge     ->  Unmerge the old compiz-fusion packages if installed, and"
                echo -e "                 Emerge/Re-emerge the latest compiz-fusion packages available." 
                echo -e "                 Example: \"`basename ${0}` emerge\""
                echo -e ""
                echo -e "  purge      ->  Purge all source files downloaded from git." 
                echo -e "                 Example: \"`basename ${0}` purge\""
                echo -e ""
                echo -e "  remove     ->  Uninstall Compiz-Fusion. Helpful when X11 is locking"
                echo -e "                 up because something in the latest developmental"
                echo -e "                 build of Compiz-Fusion is messed up."
                echo -e "                 Example: \"`basename ${0}` remove\""
                echo -e ""
                echo -e "  revert     ->  Revert to the most recent binary backups"
 		echo -e "                 of the compiz-fusion git packages." 
                echo -e "                 Example: \"`basename ${0}` revert\""
                echo -e ""

exit 0

Replace KDE's window manager on startup

Option one: add desktop settings

If Compiz Fusion runs fine and you want to launch it instead of kwin (the standard window manager for KDE), you need to set the variable KDEWM to compiz and maybe COMPIZ_OPTIONS.

The easy way to do this without affecting all users on the system is by adding the line "export KDEWM=compiz" to your user's '~/.xinitrc' file in the home folder. X reads this file as it starts up and sets the variable before starting KDE. Note that on some systems, X will read a different init file (possibly '~/.xsession' or '~./xsessionrc'). If you are unsure which to use, you can write one and symlink others to it. You can check to see if the variable was set properly by running 'printenv | grep KDEWM' in a Konsole terminal.

To make the change global, the short way is to put exports for these variables into /etc/env.d/99kde-env and then run env-update to regenerate the profile. Keep in mind this affects all users on your system and makes switching between Compiz and kwin unhandy.

However, there's a better but more complex way you may have to follow if the above methods do not work for you at all. We will make Compiz an option in login managers by creating a new session type so each user may decide on his own whether or not to use Compiz:

First we need to create a script that exports the KDEWM variable and starts KDE for us:

File: /usr/bin/

# start kde using compiz fusion instead of kwin
export KDEWM=compiz.wrapper


Then we create a new session file:

File: /usr/share/xsessions/compiz-fusion.desktop
[Desktop Entry]

Now we create a short script which wraps Compiz to run with certain arguments. If you can successfully run Compiz without arguments you won't need this. Also you may skip this if export COMPIZ_OPTIONS=... works for you (it doesn't for me). In that case you can just put the variable settings above startkde into /usr/bin/ Remember to change KDEWM=compiz.wrapper to KDEWM=compiz if you skip the next step.

File: /usr/bin/compiz.wrapper (paste your correct arguments)
/usr/bin/compiz --replace ccp --sm-disable --indirect-rendering

Last but not least you should set all file permissions:

chmod 755 /usr/bin/
chmod 755 /usr/bin/compiz.wrapper
chmod 644 /usr/share/xsessions/compiz-fusion.desktop

Logout, reload your login manager if needed, select the new session type and you're done!

Option two: using the ~/.kde/Autostart/ directory

Instead of all the above, you can just add a script to your .kde/Autostart/ directory (remember to "chmod +x" your script):

File: ~/.kde/Autostart/
/usr/bin/compiz --replace ccp &
/usr/bin/emerald --replace &     # optional
Option three: using the fusion-icon

The "fusion-icon" is a small taskbar icon which lets you select the window manager and decorator. The last selection is automatically started as soon as fusion-icon starts. The fusion icon is a replacement for beryl-manger.

At the moment (April 13 2008) there is no ebuild in the main portage tree, but there is a bugreport with it: bug 198365

The ebuild is available through layman under desktop-effects.

You can have it start up instead of metacity by going to gconf-editor and updating /desktop/gnome/session/default-session and replacing metacity with fusion-icon.

Option four: using the ~/.kde/env/ directory

This is basically a more elegant version of option one. Just add the following script to your ~/.kde/env/ directory to run the Compiz Fusion wrapper script instead of kwin when KDE starts:

File: ~/.kde/env/


If you want to make this change system-wide, you can put this script in the /usr/kde/3.5/env/ directory instead.

Common problems

Cannot use flatfiles or configuring with gconf goes haywire

The most probable cause is the use of the compiz-start script. To fix this problem, you can (and should anyway) either run

compiz --replace ccp

instead of compiz-start or you can also edit the following line in /usr/bin/compiz-start

compiz $COMPIZ_OPTIONS gconf move resize minimize place decoration wobbly fade cube rotate scale switcher zoom dbus

to look like

compiz $COMPIZ_OPTIONS ccp

Settings are disabling themselves

Just update Xorg to 7.3, and you won't get crazy configuring Compiz Fusion.

No window borders

Firstly, see in Compiz Preferences if "Window Decoration" is enabled under Effects.

Try running:

emerald --replace

Then, if you get an error like:

(emerald:17422): GLib-GObject-CRITICAL **: g_object_ref: assertion `G_IS_OBJECT (object)' failed

it may be because you have XLIB_SKIP_ARGB_VISUALS set.

Look for any occurrence of its declaration in /etc/env.d with:

grep "XLIB_SKIP_ARGB_VISUALS" /etc/env.d/*

and comment out them.

Unset the environment variable:


then reboot.

Please see discussion and bugs tab.

If 'emerald --replace' helps but after a reboot you start without borders again then check the Window-Decoration settings in CCSM.

Settings -> CompizConfig Settings Manager -> Effects -> Window-Decoration -> command

For emerald this should be 'emerald --replace'.


If launching compiz from the console in KDE returns this error:

compiz (core) - Error: Another window manager is already running on screen: 0
compiz (core) - Fatal: No manageable screens found on display :0.0

you may need to turn desktop icons on, restart X, and then run compiz again.

Using NVidia binary driver , under KDE you should define the following in your xorg.conf:
In the Screen section:

DefaultDepth 24

In the device section:

Option         "AddARGBGLXVisuals" "True"

then restart X


If launching compiz from the console in XFCE returns the following error:

compiz (core) - Error: Could not acquire compositing manager selection on screen 0 display ":0.0"
compiz (core) - Fatal: No manageable screens found on display :0.0

please make sure you have disabled the compositing manager of XFCE. You will find it in Settings > Window Manager Tweaks, under the 'Compositing' tab.

Slow Compiz under high CPU load

See this page: schedtool is in portage. You have to replace Xgl with compiz in the command.

Compiz-fusion doesn't start, Beryl was running great

Did you have beryl, which runs on your Linux perfectly, and now compiz-fusion doesn't start? Yes, I had this problem too! :)

If you see this in the console:

Missing GLX_EXT_texture_from_pixmap

You must run Compiz-Fusion with LIBGL_ALWAYS_INDIRECT=1, such as:

env LIBGL_ALWAYS_INDIRECT=1 compiz --replace ccp

I've added this variable to /etc/env.d/03opengl

"GLX_EXT_texture_from_pixmap" or "No GLXFBConfig for default depth, this isn't going to work"

If you see one of these errors and you are using ati-drivers with aiglx you should also check wether the links -> /usr/lib/opengl/ati/lib/ -> /usr/lib/opengl/ati/lib/ -> /usr/lib/opengl/ati/lib/

are set in /usr/lib.

At present, eselect sometimes only sets the first link.

If you see the second error and are using xf86-video-i810, make sure you are using xf86-video-i810-2.1.1 and not 2.2.1 ( wasn't tested). You can downgrade with:

emerge -1 =xf86-video-i810-2.1.1
Retrieved from ""

Last modified: Tue, 07 Oct 2008 10:41:00 +0000 Hits: 23,427