Window Configuration - brndnmtthws/conky GitHub Wiki

Window Configuration Settings

This page is not meant as a full on documentation but provides some general tips and default settings for popular WM/DE.

Generally black flickering may occur, Conky is designed to draw to the root desktop window. However, there are several other applications which like drawing to the root desktop window. Because of this, Conky has two options available to get around this problem:

  • You can try enabling double-buffer. Conky's double-buffer option uses the X double-buffer extension to provide a flicker-free Conky. This can be done by adding double_buffer = true to your conky config file. If the double buffer is not working you X11 installation is likely not loading the double buffer extension. Open up the Xorg configuration file (usually /etc/X11/xorg.conf) with your favourite text editor, and find the line that says: Section "Module". Then, after that line, add: Load "dbe", restart Xorg (my preferred method is the good-ole control+alt+backspace) and enjoy.
  • Conky can run in windowed mode, meaning that instead of drawing the the root window it draws to it's own window. You can move this window around and resize it by right-clicking or left-clicking on the window while holding down the Alt key. This can be accomplished by running Conky with the '-o' parameter, or by adding the following to your conky config file: own_window = true

Window manager specific configuration

Some window managers (WMs) are very picky about window settings (e.g. own_window_[foo], see Configurations) that are required for Conky to render properly.

Using the wrong settings may cause issues like: wrong window alignment, disappearing conky windows, flickering windows, bugged transparency, no click-through, hidden desktop short-cuts, etc...

Since this may be confusing for new users or annoying when changing WMs this page gives some WM specific tips and default window settings which should work. Keep in mind the given settings may be altered by your preference (eg. transparency level) and are just a starting point. Feel free to expand this page with your favorite WM (or alternative settings) to help people getting started with conky!

Wayland

Conky works on any Wayland WMs that support wlr-layer-shell extension. Wayland has no concept of "background" (root window), so if a WM doesn't support layers, conky can only open as a window (not yet implemented). If a WM has a custom layering extension, conky welcomes contributions for those.

That means that Conky can't run in the background in following window managers:

  • Mutter (Gnome) - WON'T FIX (see below for details)
  • Weston

To make conky create a Wayland window, set the out_to_x property to false, and out_to_wayland to true:

-- ~/.config/conky/conky.conf
conky.config = {
    out_to_x = false,
    out_to_wayland = true,
};

GNOME

The path GNOME devs seem to be taking is making it possible for compositors based on mutter to define their own protocols (issue), and then they will probably add their own protocol for window layers. When that happens, conky can be made to support that protocol (likely without feature gates), iff the protocol can support functionality needed by conky (drawing above desktop and behind other apps).

X11

GNOME (Ubuntu)

Requires own_window_type = 'normal' because GNOME has its own desktop window.

Use own_window_hints setting to make conky render below other windows:

own_window_hints = 'undecorated,sticky,below,skip_taskbar,skip_pager',

XFCE (Cinnamon)

The following settings should work to enable transparency.

conky.config = {
    own_window = true,
    own_window_type = 'normal',
    own_window_transparent = false,
    own_window_hints = 'undecorated,sticky,below,skip_taskbar,skip_pager',
    own_window_argb_visual = true, own_window_argb_value = 192,

    double_buffer = true,
}

Window type of normal is required because XFCE uses a xfdesktop desktop window to show the background, so using the same type might cause conky to get layered behind it.

By changing own_window_argb_value, you can alter the transparency. This does not offer click through behaviour (icons behind conky windows can not be selected/opened). To enable this feature your have to build conky with build flag BUILD_XSHAPE=ON, to see if your conky installation is build with this option check your conky -v output and search for XSHAPE under X11. If unavailable you have to recompile conky with said build flag enabled.

Alternatively, you can specify own_window_transparent to true to make the window entirely transparent instead.

Possible issues:

  • Black flickering may occur on transparent conky windows. This is caused by a design decision in Gnome (on which cinnamon is build) which has a black root window instead of the set background image [source needed]. Currently there is no work around (gnome "issue").
  • If you have got an alignment issue, everything draws on the left, make sure the option 'Disable workarounds' is disabled, see issue. To disable this option use: gsettings set org.cinnamon.desktop.wm.preferences disable-workarounds false, thanks to SethDusek for solving this issue.

MATE

Due to caja being used for desktop rendering (see related issue), MATE requires own_window_type = 'normal' same as GNOME.

LXDE & LXQt

Both LXDE & LXQt DEs use desktop panels (LXPanel & lxqt-panel, respectively). Same rules as in GNOME apply - desktop window type hides conky when desktop is clicked and as such, desktop window type is not a good fit for these DEs. Use 'normal' instead.

Awesome 4.0

Awesome-wm doesn't draw other windows over Conky, which then takes a lot of screen estate. Conky simply does not appear with own_window = false. Try this to enable background.

conky.config = {
    own_window = true,
    own_window_type = 'override',
}

GNU screen

Conky can be configured to display stats in a screen or tmux session.

Gnu Screen

-- ~/.conkyrc
conky.config = {
    out_to_x = false,
    out_to_console = true,
    total_run_times = 1 -- must be 1, screen will do the refreshing, not Conky.
};
-- EVERYTHING MUST BE ON A SINGLE LINE!
conky.text = [${time %H:%M}](/brndnmtthws/conky/wiki/free-space:${fs_free-/}|$loadavg|free-mem:$memeasyfree)

# ~/.screenrc
hardstatus on
backtick 1 5 5 conky -c /home/user/.conkyrc
hardstatus alwayslastline "%=%1`"