Skip to content

Configuration

Jump to bottom
Tin Švagelj edited this page May 3, 2026 · 1 revision

Configuration

Minimal conky configuration file can be completely empty. However, you'll likely want to configure conky to be properly drawn on your system. Running conky -C will output a basic configuration with settings you'll likely want to tweak to get the results you're happy with.

For exhaustive list of all settings, take a look at the web documentation. This page serves as an addendum - covering basic syntax and system specific options for popular WMs/DEs.

Configuration format

Conky configuration uses Lua syntax (since version 1.10).

See the Lua introduction for a guide on using Lua with conky, including a quick guide on Lua basics and details on how conky evaluates config files.

Lua pages on this wiki focus on the basics needed to write conky scripts and on conky-specific integration (Cairo, shell commands, mouse events, etc.) that you won't find elsewhere. For deeper Lua knowledge — metatables, coroutines, advanced patterns — refer to the official manual and the many tutorials, blogs, and videos available online.

Settings

Settings control the way Conky looks and behaves. They go inside a conky.config block:

conky.config = {
    update_interval = 10,
    out_to_console = true,
    out_to_stderr = false,
    template0 = [[${top_mem name \1}${alignr}${top_mem mem \1}%]],
};

Setting values should be enclosed in quotes unless they are booleans or numbers. Settings are separated by commas — a trailing comma on the last setting is allowed. Template settings (templateN) use [[ ]] brackets for their values.

A complete list of settings can be found in the web documentation or via man -P "less -p 'CONFIGURATION SETTINGS'" conky.

Variables

Variables make Conky display information. They go inside a conky.text block:

conky.text = [[
I am on ${wireless_ap wlan0} and there
are ${user_number} users on my system
]]
  • Variables without arguments: $var or ${var}
  • Variables with arguments: ${var arg1 arg2}

A complete list of variables can be found in the web documentation or via man -P "less -p 'OBJECTS/VARIABLES'" conky.

Comments

-- single line comment

--[[
multi-line
comment
]]

Comments starting with # can be used inside the conky.text block.

Colors

Colors can be specified as hex values or named colors. The # prefix is optional.

Supported hex formats:

Format Example Description
RGB #abc or abc Short hex, each nibble is doubled (a→aa)
ARGB #8abc or 8abc Short hex with alpha (8→88)
RRGGBB #ff0000 or ff0000 Standard hex
AARRGGBB #80ff0000 or 80ff0000 Hex with alpha

Named colors (e.g. white, grey, red) are supported when conky is compiled with BUILD_COLOUR_NAME_MAP enabled. Use conky -v to check.

-- in settings
default_color = 'white',
color0 = '#DCDCDC',

-- in conky.text
${color grey}Some text${color}   -- switches to grey, then back to default
${color #ff0000}Red text${color}
${color0}Uses preset color0${color}

Availability

Depending on how your installation of Conky was compiled, not all options may be available. Use conky -v to see the enabled options. If you want to alter your options, you have to recompile Conky. If you installed Conky as a package, you can contact the maintainer and ask to add a build flag or compile Conky from source.

Converting old configs to 1.10

If you have a configuration from Conky 1.9 or earlier, you can convert it using the convert.lua script:

  1. Make a backup of your configuration first.
  2. Run ./convert.lua your_config.conf in your terminal.

The script handles the bulk of the syntax changes but is not always flawless — you may need to tweak the result manually.

Window manager specific configuration

Some window managers (WMs) are very picky about window settings (e.g. own_window_[foo], see Availability) 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 and a patch that adds wlr-layer-shell support if you're comfortable patching it
  • 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 (adding wlr-layer-shell-unstable-v1 support)

GNOME desktop environment only allows extensions to draw below or on top of other windows. This is fundamentally incompatible with how conky works and requires us to either create a split in the program that's difficult and wouldn't produce the experience that's completely different to current one, or to re-write conky in JS. Neither of these options are realistic.

The only solution is that the user patches the version of Mutter they have manually. We provide an example add-layer-shell.patch patch that might save you some time. The process is relatively simple, though it will require you to install some build prerequisites (meson, libraries, etc.). It's preferred you're confident with building Mutter yourself, or you can ask someone you trust to help you out.

Process is relatively simple:

# Figure out which version you have already.
# It's important the replacement version matches or things might break/crash.
# You don't want to end up having to recover your system from a tty or reinstalling.
mutter --version

# Clone mutter in local my-mutter directory.
# Replace VERSION with the version mutter gave you: (e.g. 46.4, 48.1, 50.1)
git clone --depth 1 --branch VERSION https://gitlab.gnome.org/GNOME/mutter.git my-mutter
cd my-mutter

# Download the patch file:
curl -LO https://raw.githubusercontent.com/Caellian/mutter-layer-shell/main/.github/patches/add-layer-shell.patch

# Apply the patch:
git apply add-layer-shell.patch

# Build:
meson setup build \
    --prefix /usr \
    --buildtype release \
    --wrap-mode nofallback \
    -Dtests=disabled \
    -Dprofiler=false \
    -Ddocs=false \
    -Dinstalled_tests=false
meson compile -C build

# 5. Install (overwrites system mutter)
sudo meson install -C build

Then you'll have to do that every time mutter updates (recommended).

Alternatively you can freeze the Mutter version:

Distro Command
Arch add IgnorePkg = mutter in /etc/pacman.conf
Fedora sudo dnf versionlock mutter
Ubuntu sudo apt-mark hold mutter
openSUSE sudo zypper addlock mutter

Restart your session if you can find the "Log out" button, but even that's optional, so you might need to restart your computer.

As a convenience, you can download pre-built binaries from GH Actions. These target the latest version and will likely only work for rolling distros. You can also download the binary and replace it on your system manually, but again, this will likely cause crashes on something like Ubuntu because it's the code directly from the official main branch and depends on newer system library versions you might not have installed. Users that use distros with slower version rollout should always patch manually and optionally freeze mutter from being updated (freezing it is not ideal for security/stability, though it's an unlikely attack vector, so it's safe-ish).

If the patch doesn't work, create issues there - not on the conky project page. Note, however, that I don't actually use Mutter, and you'll likely get quicker feedback asking an LLM for help on this than creating an issue. The patch is only provided as a convenience and hasn't been thoroughly tested.

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}|free space:${fs_free /}|$loadavg|free mem:$memeasyfree]]
# ~/.screenrc
hardstatus on
backtick 1 5 5 conky -c /home/user/.conkyrc
hardstatus alwayslastline "%=%1`"

Clone this wiki locally