Lua: Introduction

Lua in Conky

Since version 1.7.1, Conky has built-in Lua support. Together with Cairo, RSVG and Imlib2 bindings, Lua allows you to draw custom graphics, process data, implement your own graphs, and more.

To check whether your Conky installation supports Lua and its bindings, run:

conky -v

The relevant build flags are BUILD_LUA_CAIRO, BUILD_LUA_RSVG, and BUILD_LUA_IMLIB2.

This part of the wiki was originally based on a cleaned up series of blog posts by mrpeachy on Crunchbang.

While Lua syntax is backwards compatible with older Conky versions, the configuration structure evolves over time as new functionality is added and older code is improved on. Most scripts will, however, continue working across versions — the only thing that might change are requires and some Conky-specific functions (in case variables are deprecated and removed).

If you spot areas that could use clearer explanations or improved formatting, feel free to contribute!

Getting Started

1. Lua Integration — loading scripts, hooks, and basic setup
2. Lua Basics — language fundamentals for Conky scripting
3. Drawing with Cairo — rendering text, shapes, and data-driven widgets
4. Shell Integration — running commands, timed execution, parsing output
5. Image Rendering — displaying raster images (Imlib2) and SVGs (RSVG)
6. Mouse Events — handling clicks, scrolls, and pointer movement

Reference Documentation

• Conky Variables — built-in variables usable from Lua via conky_parse()
• Conky Configuration — all configuration options including lua_* hooks
• Lua Reference Manual — official Lua documentation
• Cairo Manual — full Cairo API reference (Conky's bindings mirror this API)
• Imlib2 API — Imlib2 image library reference
• RSVG Documentation — librsvg SVG rendering reference

Community Resources

• Mr. Peachy's Lua blog
• wlourf's Lua scripts
• TeoBigusGeekus Weather scripts