How to Configure Conky Using Variables and Configuration Settings

Updated

Conky is configured through two complementary layers: variables, which define the individual objects Conky draws (text, bars, graphs, and more), and configuration settings, which are global parameters that control how Conky itself behaves. You write both in a Conky configuration file (commonly ~/.conkyrc or a file passed with -c), and Conky reads them at startup. The reference for both layers lives on conky.cc under the Variables and Configuration settings sections.

The two layers, and how they differ

Layer What it controls Where it appears Example scope
Variables The displayed objects: text, bars, graphs, etc. Inside the config body One object per variable
Configuration settings Global behavior of Conky itself Top of the config Applies to the whole session

The distinction matters because a variable changes what you see, while a setting changes how Conky runs. Mixing them up is a common source of configs that render but behave unexpectedly.

Step 1: Start from the reference, not from memory

Before writing anything, open the two reference sections on conky.cc:

  • Variables — the catalog of objects you can display.
  • Configuration settings — the catalog of global parameters.

Both are the authoritative lists. Because the available variables and settings depend on your Conky build and version, treat the site's lists as the source of truth rather than copying an old config from elsewhere.

Step 2: Set global behavior with configuration settings

Configuration settings go at the top of the file and shape the whole session. Typical things you decide here:

  • How Conky is positioned and sized on screen.
  • How often it updates.
  • Whether it draws its own window, background, or borders.

Input: the setting name and its value. Action: place it in the configuration-settings block at the top of the file. Expected result: the behavior applies globally to every object below it.

If a setting seems to have no effect, check that it appears before the variables it is meant to influence, and confirm the setting name matches the current reference exactly.

Step 3: Define what appears with variables

Variables are the objects Conky displays. Each variable produces one piece of output — a line of text, a bar, a graph, and so on.

Input: a variable name, plus any arguments it accepts. Action: place it in the body of the config, one object per line or block. Expected result: that object is drawn in the Conky window.

Practical rules:

  • Use the Variables reference to confirm the exact name and the arguments each variable takes.
  • Keep one concern per line so a broken object is easy to isolate.
  • If an object does not appear, verify the variable exists in your build before changing anything else.

Step 4: Extend beyond the built-in set

When variables and settings are not enough, Conky can be extended:

  • Lua API — add custom behavior by scripting against the Lua API.
  • Compiling — build Conky from source if you need options your package does not include.
  • Docker — run Conky in a container using the Docker guide.

These are separate from everyday configuration and are documented in their own sections on conky.cc.

Step 5: Verify and troubleshoot

After editing:

  1. Reload or restart Conky so it re-reads the file.
  2. Confirm each object you added actually renders.
  3. If something is missing, re-check the variable name against the Variables reference.
  4. If behavior is wrong, re-check the setting against the Configuration settings reference.

Common sticking points:

  • Wrong layer: a variable placed where a setting belongs (or vice versa) will not do what you expect.
  • Stale names: variables and settings change between versions; an old config may reference names your build no longer has.
  • Silent failures: an unrecognized variable typically just does not render, so absence of output is the signal to check the reference.

Where to go for more

  • Variables and Configuration settings — the two core references for configuration.
  • Lua API — for custom behavior.
  • About — what Conky is and what it can do.
  • Compiling and Docker — build and container options.
  • Contributing and Syntax Highlighting — for working on Conky and enabling .conkyrc highlighting.
  • Wiki — the GitHub wiki holds user configs, Lua scripts, and FAQs, useful as worked examples once you understand the two layers above.