This article describes some common problems you may encounter when starting Compiz, and what you can do about them.

What you should see on startup

Checking for problems

compiz --replace ccp & emerald --replace &

Common Mistakes


Generally speaking, compiz only requires a running X session with working graphics drivers supporting GLX_EXT_texture_from_pixmap. However, there are some cases where compiz can not start because of the environment or other similar software running. Environments where compiz is known to be inhibited are Gnome Shell and LXDE. For Gnome3, you will need to enable Forced Fallback Mode in System Settings. LXDE uses an Openbox session which does not allow any window manager to replace it. You will need to use a non-openbox session for compiz to work. Other window managers with compositing enabled may not allow another compositing window manager to replace it, such as xfwm4. You will want to make sure compositing is disabled for your default window manager before running compiz.

nVidia Cards

If you have an Nvidia card, make sure you are using the proprietary (sometimes referred to as restricted) Nvidia driver. The "experimental" Nouveau 2D/3D driver is considered "under development" and is not offered on Ubuntu until it becomes more stable.. some distributions offer it and apparently it runs compiz effectively, for some. If you already have the proprietary Nvidia driver installed, you can help with the development of Nouveau by sending information about your card.. The nv driver does not support 3D acceleration of any kind and cannot be used to run compiz.

If you're experiencing performance sluggishness, try starting compiz with the --loose-binding option. With loose binding, textures are enabled when created, and the nvidia driver seems a bit slow when binding textures, which is why this option yields a significant performance improvement.

With nvidia drivers earlier than version 100.14.09 drivers, you may not be able to see any window borders. To fix the problem, either run the following command:

sudo nvidia-xconfig --add-argb-glx-visuals -d 24

Or edit the Screen section of your /etc/X11/xorg.conf file to contain the following line:

    DefaultDepth 24

And edit the Device section to contain the following line:

    Option "AddARGBGLXVisuals" "true"

Then restart X.

ATI Cards

If you are using an ATI card, Compiz requires at least a Radeon 7000 (or M6). For 7000 to HD5xxx series cards, you can use the open source "radeon" driver. HD2xxx and later series cards are also supported by the proprietary "fglrx" driver. Any of the "HD" series is supported by latest catalyst... Catalyst 9.3 or earlier must be used for legacy cards

Intel GMA Cards

If you are using an Intel GMA card with AIGLX, you will need to start Compiz with LIBGL_ALWAYS_INDIRECT=1 prepended to the command line and run compiz with the --indirect-rendering option, as with the following example:

LIBGL_ALWAYS_INDIRECT=1 INTEL_BATCH=1 compiz --replace --indirect-rendering --sm-disable ccp &

Apple iBooks

If you are using a new world iBook with a Radeon video card, please refer to the article about using ATI with AIGLX.

Common Problems

No Window Borders

When you start Compiz, your window borders disappear and you can no longer see each window's title, or minimize/maximize/close buttons. There are many potential causes for this very common problem, and is usually indicative of a Compiz or X server misconfiguration, or a misunderstanding of how Compiz is supposed to work.

Is a Window Decorator Running?

Check whether a window decorator is running. Enter the following command into a console window to find out:

ps ax | egrep '(decorator|emerald)'

If you don't see any commands starting with "emerald", "gtk-window-decorator", or "kde-window-decorator", then no window decorator is running. Try starting Emerald with the following command:

emerald --replace

Is the Window Decoration Plugin Enabled?

Check whether the Window Decoration plugin is enabled. It must be enabled for the borders drawn by window decorators to become visible. Run ccsm, then ensure that the check box next to "Window Decoration" is marked.

Is Compiz Running?

There may be a problem with the way Compiz is being started. Enter this command into a console window to find out how and whether Compiz is running:

ps ax | grep compiz

If you don't see a command starting with "compiz" or "compiz.real" in the output, then Compiz is failing to start altogether. Please refer to the Common Mistakes section above to see whether anything describes your situation. Also check the Setup article to see whether your X server was properly configured.

If you do see a "compiz" or "compiz.real" command in the output, check whether "ccp" is part of the command line. The ccp plugin is required for Compiz to interact with settings made in ccsm. If it's missing from your Compiz command line, you should edit your startup process to include ccp in Compiz's command line, as in this example:

compiz --replace ccp

Using an nVidia Card?

As described in the Common Mistakes section, you may need to make some adjustments to your /etc/X11/xorg.conf file in order to see window borders even if everything else is working perfectly.

Black Window Bug

Black windows are caused by a bug/limitation in nVidia's implementation of GLX_EXT_texture_from_pixmap. Turning off the blur effect may delay the appearance of the bug. Running compiz with the --indirect-rendering option should almost completely eliminate black windows, although syncing to VBlank won't work with indirect rendering.

The black window bug should have been mostly fixed as of version 100.14.19 of the nvidia driver. Using that or a later version of the driver, you will almost certainly not experience the problem with direct rendering, though you may still see a black screen if you repeatedly switch to and from virtual consoles.

White Screen

A white screen can be a symptom of different problems depending on your video card. For nVidia cards, it usually means that the nvidia driver is not enabled or operational.

This problem is characterised by a completely white screen where desktop effects (such as rotating the cube with <Ctrl><Alt>Left or <Ctrl><Alt>Left) continue to work, but no window contents are visible. It means that there is a bug with binding pixmaps to textures. This usually means that for whatever rendering method you are using, the GLX_EXT_texture_from_pixmap extension is broken. Please upgrade your driver, X server, and/or Xgl if you are using it.

"White cube of Death" on KDE

When using Compiz with KDE and a NVIDIA card, you may encounter the "White Cube of Death" problem. When starting KDE, for a short time you can see your desktop, then everything turns white. You are still able to move the mouse (the mouse pointer changes over icons) and rotate the cube, but all cube faces are white.

A workaround is to log in with a different session (e.g. Window Maker or FVWM) which does not use Compiz, then start kcontrol, go to KDE Components -> Session Manager and select "Start with an empty session". Now Compiz should work without problems. If you cannot log in and start kcontrol, log in at a text console and remove the KDE Session configuration file with the following command:

rm ~/.kde/share/config/ksmserverrc

It seems that the bug is created by an entry in ~/.kde/share/config/ksmserverrc reading something like:


Windows Don't Update

When using the intel or ati driver with AIGLX, you may notice that all your windows seem to be frozen even as you interact with them. Nothing in any window updates until you rotate the cube or otherwise switch viewports.

Adding the following line to the Device section of your /etc/X11/xorg.conf file should fix the problem:

    Option "XAANoOffscreenPixmaps" "true"

What to do if compiz crashes

In order to be able to track down crash reasons, the developers mainly need two things:

A backtrace of a compiz crash can be created using the crash handler plugin which is part of the plugins-extra package. After enabling that plugin, a crash trace with the name compiz_crash-<pid>.out is written everytime compiz crashes to a directory specifiable in the crashhandler plugin options (by default: /tmp). That dump alone is not very helpful, though, because it doesn't contain source code references. In order to get them, debug information needs to be installed. How to do that depends on your distribution:

As soon as you have a backtrace with debug information, submit them either to the forums or to the bug tracker.

Troubleshooting (last edited 2012-05-24 16:39:43 by c-75-70-115-228)