Configuration File - brndnmtthws/conky GitHub Wiki

When starting up, conky will try to find and use the default configuration file unless -c <path> argument was provided.

By default, conky package provided by most distributions doesn't install the default config file in the standard XDG path for the user or the global config path - doing so would overwrite it on updates. This means that when using conky, in order to customize the output, one has to manually create the configuration file.

-C argument may be used to make conky output the default configuration file. Piping it into the standard XDG config path for a user will create a working initial config file:

mkdir $XDG_CONFIG_HOME/conky
conky -C > $XDG_CONFIG_HOME/conky/conky.conf

^{NOTE: this feature requires conky to have been built with BUILD_BUILTIN_CONFIG; this build option should be enabled for official distro packages (unless it's a minimal build flavor).}

The path where the config file is placed can be one of the following:

• $XDG_CONFIG_HOME/conky/conky.conf - standard XDG configuration path for current user.
• $HOME/.conkyrc - old path to the config file, kept for backwards compatibility.
• /etc/conky/conky.conf - system wide configuration file.

Conky will attempt to load the config file from those paths, in the listed order. If none of the paths exists (configuration file wasn't created), the default one will be used if conky was built with BUILD_BUILTIN_CONFIG, if not, conky will error out with the appropriate error message.

Linux distributions that include conky as part of the installed system should prefer using the last (system wide) configuration path in order to allow different users to customize their personal configuration files according to their needs and preferences.

Depending on how your installation of Conky was compiled, not all of the options mentioned in this documentation may be available. conky -v can be used to see the enabled options of your Conky installation.

If some options you want aren't available, you can compile conky on your own to enable them. Conky packages provided by most distributions generally ship with default build settings. Default build settings don't enable hardware specific features, experimental/buggy features and some features which may drastically affect performance.

The online documentation provides a detailed overview of all supported configuration settings: SETTINGS

Settings are used to configure appearance and behavior of conky when it's ran. Some settings can be dynamically updated from Lua, some require a restart to be applied.

Enabled ones can be listed offline from man by running: man -P "less -p 'CONFIGURATION SETTINGS'" conky.

You can read manual in your browser too: man -H conky.

The online documentation provides a list of all variables that are supported by conky.text: VARIABLES

Variables are used to display dynamic information within content displayed by conky. They are processed in a single pass (with some minor caveats), which means they can't be nested. The only exception to this is the ${templateN} variable which may be used to perform substitutions before evaluating contained variables.

Enabled ones can be listed offline from man by running: man -P "less -p 'OBJECTS/VARIABLES'" conky.

You can read manual in your browser too: man -H conky.

Conky configuration file is a Lua script file. The most basic form of the configuration file doesn't require any knowledge of the Lua scripting language, but knowing Lua will greatly help with more advanced functionality.

Settings go into conky.config table:

conky.config = {
  setting_name = setting_value,
  -- other settings ...
};

• Setting value should be enclosed in quotes unless it is a boolean or number.
  • Check out the documentation to see what the correct value format is and what each setting does.
  • Settings without arguments can use true or false.
• Settings (table values) should be separated by a comma.

Comments start with double-dash --, and there's also multi-line comments which are enclosed in double-brackets ([[ ]]):

-- single line comment

--[[
  this comment spans
  multiple lines
]]

conky.text contains text content to be drawn by conky and its value should in most cases be placed in double-brackets ([[ ]]) as well:

conky.text = [[
  some text content
# this is a comment in text section
  some more visible text
]]

• Comments in text section are lines that start with a #.
• Colors do not use the # any more, so #DCDCDC becomes DCDCDC (e.g. ${color DCDCDC} and color0 = 'DCDCDC').

Variables without arguments can either be written without or with braces - both $var and ${var} are valid. Variables with arguments should be enclosed in braces: ${var arg1 arg2}.

Here's a minimal example to showcase the syntax of a complete file:

conky.config={
  update_interval=10,
  out_to_console=true,
  out_to_stderr=false,
  template0 = [[there $1, I hope you're doing well]]
};

conky.text = [[
Hello ${template0 user}!
]]

• templateN setting uses the double-brackets ([[ ]]), which allows it to be a multi-line string.

One of the best way of learning what can be done (and how to do it) is to go though existing configs and inspect how they achieve effects you like. They range from very simple ones to very advanced.

update_interval 10
out_to_console yes
out_to_stderr no

TEXT
I am on ${wireless_ap wlan0} and there
are ${user_number} users on my system

• Install Lua if you don't have it installed already.
• Download the script: convert.lua
• Run ./convert.lua your_config.conf in your terminal.