{"id":13896674,"url":"https://github.com/varingst/awesome-conky","last_synced_at":"2026-03-07T03:03:10.680Z","repository":{"id":42680801,"uuid":"80207384","full_name":"varingst/awesome-conky","owner":"varingst","description":"Make AwesomeWM 4.0 widgets displaying system information from conky","archived":false,"fork":false,"pushed_at":"2018-06-15T19:55:30.000Z","size":49,"stargazers_count":30,"open_issues_count":0,"forks_count":1,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-11-02T03:01:49.703Z","etag":null,"topics":["awesomewm","conky","lua","widget-framework"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/varingst.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-01-27T12:56:35.000Z","updated_at":"2024-10-31T08:52:54.000Z","dependencies_parsed_at":"2022-08-30T20:40:16.701Z","dependency_job_id":null,"html_url":"https://github.com/varingst/awesome-conky","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/varingst/awesome-conky","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/varingst%2Fawesome-conky","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/varingst%2Fawesome-conky/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/varingst%2Fawesome-conky/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/varingst%2Fawesome-conky/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/varingst","download_url":"https://codeload.github.com/varingst/awesome-conky/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/varingst%2Fawesome-conky/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30206339,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-06T19:07:06.838Z","status":"online","status_checked_at":"2026-03-07T02:00:06.765Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["awesomewm","conky","lua","widget-framework"],"created_at":"2024-08-06T18:03:04.678Z","updated_at":"2026-03-07T03:03:10.661Z","avatar_url":"https://github.com/varingst.png","language":"Lua","funding_links":[],"categories":["Lua"],"sub_categories":[],"readme":"# Conky widgets for Awesome WM 4\n\n`conky-awesome` is a framework for making [awesome](https://awesomewm.org) widgets displaying system information from [conky](https://github.com/brndnmtthws/conky)\n\n`conky-awesome` provides some optional keybindings to manange conky's own\nX-window, but you can also run `conky-awesome` headless by configuring conky\nwith `out_to_x = false` and only have it update your widgets.\n\n## Requirements\n* conky\n* awesome with dbus support\n* [lua bindings to dbus](https://github.com/daurnimator/ldbus)\n\n## Installation\nClone this repo to `~/.config/awesome/conky`\n\n## Configuration\n\n### conkyrc\n\n```\nconky.config = {\n    .....\n    lua_load = \"~/.config/awesome/conky/conky-dbus.lua\",\n    lua_draw_hook_pre = \"conky_update_awesome\",\n}\n```\n\n### rc.lua\n\n```\nlocal conky = require(\"conky\")\n```\n\nThis is all that is required to have conky start at launch.\nRestarting awesome will not spawn additional conky clients.\n\nTo launch conky with custom options, i.e. a different `conkyrc`:\n\n```\nconky.options = \"-c ~/.conky/my_special_conkyrc\"\n```\n\n#### Keybindings\n\nThe conky client's own window defaults to being behind all other windows.\n\nBind keys for raising the client window on top.\n\n```\nglobalkeys = awful.util.table.join(\n    awful.key( .....\n    .....\n    conky.show_key(\"F12\"),                -- conky window on top while held\n    conky.toggle_key(\"F12\"), { modkey })  -- toggle conky on top\n)\n```\nBoth functions have this signature:\n`(keystring, [ modifier table ])`\n\nYou can also provide functions to call when the window is raised and lowered\n\n```\nconky.raise = function(c) c.opacity = 1.0 end\nconky.lower = function(c) c.opacity = 0.4 end\n````\n\nIf you are running conky with a non-standard window class, by setting\n`own_window_class` in `conkyrc`, you must also set this in `rc.lua` for\nthe keybindings to work:\n\n```\nconky.class = \"MyClass\"\n```\n\n#### Client Window Properties\n\nTo set [properties](https://awesomewm.org/apidoc/classes/client.html#Object_properties) for the client window (defaults shown):\n```\nconky.properties = {\n    floating = true,\n    sticky = true,\n    ontop = false,\n    skip_taskbar = true,\n    below = true,\n    focusable = true,\n    titlebars_enabled = false,\n}\n```\n\nFor these properties to apply properly when awesome is started and restarted,\nthe following must be added to the `Rules` section in `awesome/rc.lua`:\n\n```\nawful.rules.rules = {\n    ....\n    conky.rules()\n}\n```\n\nExtra properties may be provided to be applied on launch, as per [awful.rules](https://awesomewm.org/apidoc/libraries/awful.rules.html):\n```\nawful.rules.rules = {\n    ....\n    conky.rules({ properties = { tag = \"3\" }, callback = function(c) ... end })\n}\n```\n\n## Making Conky Widgets\n\nConky widget declaration:\n```\n{\n  icon             = \u003cstring\u003e,     -- image filename\n  label            = \u003cstring\u003e,     -- text for a label\n  conky            = \u003cstring\u003e,     -- the string conky evaluates with conky_parse()\n  background       = \u003ctable\u003e,      -- background properties table\n  updater          = \u003cfunction\u003e,   -- custom updater function\n  buttons          = \u003ctable\u003e,      -- buttons to connect to the widget\n  signals          = \u003ctable\u003e,      -- signals to connect to the widget\n  tooltip          = \u003ctable\u003e,      -- tooltip for the widget\n  \u003cwibox property\u003e = \u003cvalue\u003e       -- properties for the widgets\n  {                          -- any number of child widgets:\n    \u003cconky declaration\u003e,     -- nested conky widget declarations\n    \u003ccanned conky widget\u003e,   -- premade widgets from .config/awesome/conky/widgets\n    \u003cany widget\u003e             -- to place other widgets in-between conky widgets\n  }\n}\n```\n\nA conky widget consists of up to four subwidgets, all optional:\n  - `icon` declares a [wibox.widget.imagebox](http://awesomewm.org/apidoc/classes/wibox.widget.imagebox.html) instance\n  - `label` declares a [wibox.widget.textbox](http://awesomewm.org/apidoc/classes/wibox.widget.textbox.html) instance\n  - `conky` declares a [wibox.widget.textbox](http://awesomewm.org/apidoc/classes/wibox.widget.textbox.html) instance\n  - `background` declares a [wibox.container.background](http://awesomewm.org/apidoc/classes/wibox.container.background.html) instance\n\n### A minimal widget\n\nSimply declaring a string to be evaluated by conky:\n```\ns.mywibox:setup {\n  .....\n  conky.widget({ conky = \"CPU: ${cpu}% MEM: ${memperc}% GPU: ${hwmon 0 temp 1}\" }),\n  ....\n}\n```\n\n### Icons and labels\n\nSimple example with an icon and a text label:\n```\nconky.widget({\n    icon = \"my_neat_cpu_icon.png\",\n    label = \"CPU:\",\n    conky = \"${cpu}\"\n})\n\n```\n\n### Subwidgets\n\nSetting wibox properties individually for subwidgets:\n\n```\nconky.widget({\n  label = \"CPU:\",\n  conky = \"${cpu}\",\n\n  -- properties for the background wibox\n  background = { bg = \"red\" },\n\n  -- properties for the label wibox\n  labelbox = { font = \"Font for Label\" },\n\n  -- properties for the conky wibox\n  conkybox = { force_width = 30, align = \"right\" },\n\n  -- properties for the icon wibox\n  iconbox = { opacity = 0.8 },\n})\n```\n\n### Child widgets\n\nChild widgets inherit properties from their parents.\n\nAny number of child widgets can be declared, and will be placed to the right\nof its parent.\n\n```\nconky.widget({\n  font = \"My Neat Font\",\n  label = \"CPU:\",\n  conky = \"${hwmon 1 temp 1}\",   -- cpu temp\n\n  { -- child widget 1 inherits \"My Neat Font\"\n    label = \"Core 1:\",\n    { conky = \"${cpu cpu1}\" },   -- as does the grandchildren\n    { conky = \"${cpu cpu2}\" },\n  },\n\n  { -- child widget 2 inherits \"My Neat Font\"\n    label = \"Core 2:\",\n    { conky = \"${cpu cpu3}\" },   -- as does the grandchildren\n    { conky = \"${cpu cpu4}\" },\n  },\n\n  ....\n\n  {\n    font = \"Font for Ram\"    -- different font for RAM child widget\n    label = \"RAM:\"\n    conky = \"${memperc}\"\n  }\n})\n```\n\nChild widgets inherit subwidget properties from their parent.\n\n```\nconky.widget({\n  label = \"Parent\",\n  background = { bg = \"black\" },\n  labelbox = { force_width = 30 },\n  {\n    label = \"Child\",\n    labelbox = { align = \"right\" },\n    {\n      -- this widget has a black background,\n      -- and a left-aligned label widget 30 pixels wide\n      label = \"GrandChild\",\n      labelbox = { align = \"left\" },\n    }\n  }\n})\n```\n\n### Updater Function\n\nTo change the widget based on updates from conky, provide\nan updater function with the following signature:\n\n`function updater(conky_update, conky_wibox, icon_wibox, label_wibox, background)`\n\nWhere `conky_update` is the update from conky, and the rest are the subwidget\nwiboxes.\n\nA CPU widget that changes its background color to red if the load goes above 80%:\n\n```\nconky.widget({\n  label = \"CPU:\",\n  conky = \"${cpu}\",\n  background = { bg = \"grey\" },\n\n  updater = function(conky_update, conky_wibox, _, _, background)\n    conky_wibox:set_text(conky_update)\n\n    if tonumber(conky_update) \u003e 80 then\n      background.bg = \"red\"\n    else\n      background.bg = \"grey\"\n    end\n  end\n})\n```\n\n### Buttons\n\nProviding a table of button declarations allows you to change the widget\nbased on button pressed.\n\nA CPU widget that changes its background color to blue while the user holds\nCTRL and \u003cmouse1\u003e:\n\n```\nconky.widget({\n  label = \"CPU:\",\n  conky = \"${cpu}\",\n  background = { bg = \"red\" },\n  buttons = {\n    {                      -- declaration of single button\n      { \"Control\" },       -- table of modifiers\n      1,                   -- key, here \u003cmouse1\u003e\n      function(conkybox, iconbox, labelbox, background)  -- function for\n        background.bg = \"blue\"                           -- button press\n      end,\n      function(conkybox, iconbox, labelbox, background)  -- (optional) function\n        background.bg = \"red\"                            -- for button release\n      end\n    },\n    ...                    -- more button declarations\n  }\n})\n```\n\n### Signals\n\nProviding a table of signals and conky-awesome connects them for you.\n\nA CPU widget showing the load on all four cores while the mouse hovers over it:\n\n```\nlocal cpu_widget = (function()\n  local conkyb = {                    -- properties are not passed to\n    forced_width = 30,                -- already built child widgets, so\n    align = \"right\",                  -- shared properties are declared here\n  }\n\n  local cores = conky.widget({        -- building the widget here to close\n    conkybox = conkyb,                -- up in signal functions below\n    { conky = \"${cpu cpu1}%\" },\n    { conky = \"${cpu cpu2}%\" },\n    { conky = \"${cpu cpu3}%\" },\n    { conky = \"${cpu cpu4}%\" },\n  })\n  cores.visible = false               -- widget starts out with cores hidden\n\n  return {                            -- widget declaration\n    conkybox = conkyb,                -- shared properties\n    conky = \"${cpu}%\",              -- total load %\n    signals = {\n      ['mouse::enter'] = function(conkybox, iconbox, labelbox, background)\n        cores.visible = true          -- on hover, show cores and hide\n        conkybox.visible = false      -- total load\n      end,\n      ['mouse::leave'] = function(conkybox, iconbox, labelbox, background)\n        cores.visible = false         -- reset when mouse leaves\n        conkybox.visible = true\n      end,\n    },\n    cores,\n  }\nend)()\n```\n\n### Tooltip\n\nSimply a table to pass to [awful.tooltip()](https://awesomewm.org/doc/api/classes/awful.tooltip.html).\n\nA simple 24 hour clock with a date tooltip:\n\n```\nconky.widget({\n  conky = \"${time %R}\",\n  conkybox = { align = \"center\" },\n  tooltip = {\n    timer_function = function() return os.date(\"%A %B %d %Y\") end,\n  }\n})\n```\n\n### Canned Widgets\n\nCanned widgets, located in `awesome/conky/widgets/`, can be included by providing\nits filename, without the lua extension, in place of any widget declaration.\n\n```\nconky.widget({\n  conky = \"CPU: ${cpu}\"\n  {\n    \"battery\"       -- battery widget, from widgets/battery.lua\n  }\n})\n```\n\nCanned widgets can be configured as follows:\n\n```\nconky.config.\u003cwidget\u003e = { \u003coption\u003e = \u003cvalue\u003e }\n```\n\nTo make a canned widget, have the module return a constructor function\nthat takes a table of options and returns a widget declaration. The top\nof the file should contain a comment describing use and configuration.\n\n```\n-- usage\n--[[\n  Description and instructions goes here\n--]]\n\nreturn function(options)\n  -- apply options\n  return {\n    -- declare widget\n  }\nend\n```\n\nPlease contribute if you make anything cool or useful.\n\n### Mixins\n\nMixins, located in `awesome/conky/mixins/`, are for extending a widget\ndeclaration with common functionality. Below the `keep-max` mixin extends\nthe CPU widget declaration with functionality that tracks and displays both\nthe current and highest value, in this case CPU core temperature.\n\n```\nconky.widget({\n  conky.mixin(\"keep-max\", {\n    icon = beautiful[\"icon-hardware-cpu\"],\n    conky = \"${hwmon temp 2} ${hwmon 3 temp 3}\",\n    {\n      conky = ${cpu}% \",\n    }\n  })\n})\n```\n\nAny number of mixins may be provided, and they are applied in order to the\nprovided declaration.\n\n```\nconky.mixin(\"keep-max\", \"alert-on\", ..., \u003cwidget declaration\u003e)\n```\n\nTo make a mixin, have the module return a constructor function\nthat takes a widget declaration to extend. The top of the file should\ncontain a comment describing use and configuration.\n\n```\n-- usage\n--[[\n  Description and instructions goes here\n--]]\n\nreturn function(widget_decl)\n  \u003cdefine stuff\u003e\n  \u003cextend widget\u003e\n  return widget_decl\nend\n```\n\n## Errors and Debugging\n\n`conky-awesome` will eject widgets that are misbehaving. This means that the\nwidget will not receive further updates from `conky`. A widget will be ejected\nif it throws an error, of it receives an empty string as an update.\n`conky-awesome` will display a notification with a widget is ejected.\n\nIf you `CTRL+RightClick` on the conky widget, `conky-awesome` will display a\ndebug feed, showing the variables passed to `conky` together with its last\nupdated value. The debug feed will also list ejected widgets.\n\n## Caveats and Gotchas\n\n### Conky\n\nIf you change your `.conkyrc` while conky is running, conky will restart itself\nbut appears to not be reloading its lua files. Conky will complain about\n`conky_update_awesome` being nil. Simply kill the process and start conky\nmanually.\n\n### Awesome in Xephyr\n\nIf you start a nested awesome in Xephyr, you will need to start it in a\nseparate dbus session. You can do this by starting the nested awesome with\n`dbus-launch awesome`\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvaringst%2Fawesome-conky","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvaringst%2Fawesome-conky","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvaringst%2Fawesome-conky/lists"}