Lua API

Conky features a Lua programming API and also ships with Lua bindings for some useful libraries. Note that the bindings require tolua++.

To use Lua with Conky, first make sure you have a version of Conky with Lua support enabled (conky -v will report this). Conky defines certain global functions and variables that can be accessed from Lua code running inside Conky. Scripts must first be loaded using the lua_load configuration option. You can then call Lua functions through Conky's $lua, $lua_read, and Lua hooks.

Be careful when creating threaded objects through the Lua API. You could end up with a large number of threads running if a thread is created with each iteration.

Note: to accommodate certain features in the Cairo library's API, Conky will export a few additional functions for the creation of certain structures. These are documented below.

Call this method to return a new RsvgDimensionData structure. A creation function for this structure is not provided by the Rsvg API.

After calling this, you should use tolua.takeownership(rect) on the return value to ensure ownership is passed properly.

Call this method to free memory allocated by RsvgDimensionData:create.

You should call tolua.releaseownership(dd) before calling this function to avoid double-frees, but only if you previously called tolua.takeownership(dd)

Gets the values of an existing RsvgDimensionData.

Sets the values of an existing RsvgDimensionData.

Call this method to return a new RsvgRectangle structure. A creation function for this structure is not provided by the Rsvg API.

After calling this, you should use tolua.takeownership(rect) on the return value to ensure ownership is passed properly.

Call this method to free memory allocated by RsvgRectangle:create.

You should call tolua.releaseownership(rect) before calling this function to avoid double-frees, but only if you previously called tolua.takeownership(rect)

Gets the values of an existing RsvgRectangle.

Sets the values of an existing RsvgRectangle.

Call this function to return a new cairo_font_extents_t structure. A creation function for this structure is not provided by the cairo API.

After calling this, you should use tolua.takeownership(cfe) on the return value to ensure ownership is passed properly.

Call this function to free memory allocated by cairo_font_extents_t:create.

You should call tolua.releaseownership(cfe) before calling this function to avoid double-frees, but only if you previously called tolua.takeownership(cfe)

Call this function to return a new cairo_matrix_t structure. A creation function for this structure is not provided by the cairo API.

After calling this, you should use tolua.takeownership(cm) on the return value to ensure ownership is passed properly.

Call this function to free memory allocated by cairo_matrix_t:create.

You should call tolua.releaseownership(cm) before calling this function to avoid double-frees, but only if you previously called tolua.takeownership(cm)

Renders an image onto a cairo_t, using imlib2. In some cases using a cairo_t and exact coordinates is more useful.

ArgumentDescription
filePath to the image to render.
crThe cairo_t to render to.
x,yPosition to render the image.
width, heightThe width and height to draw the image
alphaThe transparency of the image 1.0 is solid 0.0 is fully translucent.

require('cairo_imlib2_helper') in your lua file.

Call this function to return a new cairo_text_extents_t structure. A creation function for this structure is not provided by the cairo API.

After calling this, you should use tolua.takeownership(cte) on the return value to ensure ownership is passed properly.

Call this function to free memory allocated by cairo_text_extents_t:create.

You should call tolua.releaseownership(cte) before calling this function to avoid double-frees, but only if you previously called tolua.takeownership(cte)

A string containing the build architecture for this Conky instance.

A string containing build information for this Conky instance, including the version, build date, and architecture.

A string containing the path of the current Conky configuration file.

This table contains some information about Conky's internal data. The following table describes the values contained:

KeyValue
update_intervalConky's update interval (in seconds).

This function takes a string that is evaluated as per Conky's TEXT section, and then returns a string with the result.

Sets Conky's update interval (in seconds) to 'number'.

Returns the current cairo_surface_t for the active display output, or nil if no graphical surface is available. This is the preferred, backend-agnostic way to obtain a drawing surface for use with Cairo.

The returned surface is only valid for the current draw cycle. Do not cache it across frames; call conky_surface() each time your draw hook is invoked.

Example usage:

require('cairo')
function conky_draw()
  local surface = conky_surface()
  if not surface then return end
  local cr = cairo_create(surface)
  -- draw ...
  cairo_destroy(cr)
end

A string containing the version of the current Conky instance.

This table contains read-only information about Conky's window. The following table describes the values contained:

KeyValue
drawableDeprecated. Window's drawable (Xlib Drawable). Use conky_surface() instead.
visualDeprecated. Window's visual (Xlib Visual). Use conky_surface() instead.
displayDeprecated. Window's display (Xlib Display). Use conky_surface() instead.
widthWindow width in layout points (pt; logical).
heightWindow height in layout points (pt; logical).
pixel_size.xWindow width in device pixels (px; physical).
pixel_size.yWindow height in device pixels (px; physical).
scaleScaling factor of the buffer (dpi; pixel_size / size).
border_inner_marginWindow's inner border margin (in pixels).
border_outer_marginWindow's outer border margin (in pixels).
border_widthWindow's border width (in pixels).
text_start_xThe x component of the starting coordinate of text drawing.
text_start_yThe y component of the starting coordinate of text drawing.
text_widthThe width of the text drawing region.
text_heightThe height of the text drawing region.

NOTE: This table is only defined when a GUI output is active. The drawable, visual, and display fields are X11-specific and deprecated.

Renders an image onto a cairo_surface_t, using imlib2. Returns the amount the image was scaled by

ArgumentDescription
filePath to the image to render.
csThe cairo_surface_t to render to.
x,yPosition to render the image.
scale_x, scale_yThe amount to scale the image, 1.0 provides no scaling, 2.0 for twice the size and
0.5 for half size etc.
Default value: No Scaling (1.0,1.0)

require('cairo_imlib2_helper') in your lua file.

Renders text to a cairo_t using HarfBuzz and FreeType. This provides significantly better text rendering than Cairo's built-in functions.

ArgumentDescription
crThe cairo_t to render to.
x,yPosition to render the text.
textThe text to render.
fontThe name of the font to be used, Fontconfig is used to search for the font.
font_sizeThe font size.
alignmentOne of CAIRO_TEXT_ALIGN_LEFT, CAIRO_TEXT_ALIGN_RIGHT, CAIRO_TEXT_ALIGN_CENTER.
Default value: CAIRO_TEXT_ALIGN_LEFT
languageA string containing a BCP 47 language tag.
Default value: en
scriptA string containing a ISO 15924 script tag.
Default value: auto-detect from text
directionA string representing text direction eg LTR, RTL or TTB
Default value: auto-detect from text otherwise LTR

Used to calculate how many pixels will be required to render a string with cairo_text_hp_show returns a pair of int's with width and height.

ArgumentDescription
crThe cairo_t to render to.
textThe text to render.
fontThe name of the font to be used, Fontconfig is used to search for the font.
font_sizeThe font size.
languageA string containing a BCP 47 language tag.
Default value: en
scriptA string containing a ISO 15924 script tag.
Default value: auto-detect from text
directionA string representing text direction eg LTR, RTL or TTB
Default value: auto-detect from text otherwise LTR

cairo_text_hp_show and cairo_text_hp_text_size both cache internal font details, this function clears those caches.

2026 Conky developers, updated local dev