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.

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