This wiki will shut down!

Please note that this wiki will be made read-only and eventually be taken offline.

A replacement is being discussed at We'd be happy to have more input for that discussion and volunteers who help us migrate the content of this wiki to its replacement.


From awesome
Jump to: navigation, search
Time machine.pngThis page contains version-specific content
Code or instructions listed here may not work for all versions of Awesome.
You can help the community by creating pages for other versions.
Proven working in: 3.4.x
Pages for other versions: 3.5


Menu has just been opened
Text "fi" has been entered
Inside the Development category

Menubar is a dmenu-like applications menu extension for Awesome.

Awesome certainly lacks a nice menu widget out of the box. The default only works on Debian and isn't very fancy. Another option is, which parses directories for .desktop files to generate the menu, but it is't keyboard-centric (which is controversial to Awesome ideology).

Menubar uses the same data source as (it actually uses freedesktop's code under the hood). After a hotkey is pressed, a menu appears that contains all categories (as defined in menu_gen.lua) and all applications. Entries are filtered as you start to type, in a way similar to dmenu; entries that start with the entered text come first, entries that match the filter somewhere in the middle come second.

You can also go inside the category by highlighting it and hitting Return. This will result in the menubar showing only the applications from the selected category.

How to start[edit]

  • Create a new folder called menubar in your ~/.config/awesome/ folder. Copy the downloaded files (init.lua, menu_gen.lua, prompt.lua and utils.lua) into it (so they become ~/.config/awesome/menubar/init.lua etc.).
  • Open your rc.lua file and add these lines:
 menubar.cache_entries = true
 menubar.app_folders = { "/usr/share/applications/" }
 menubar.show_categories = true   -- Change to false if you want only programs to appear in the menu
 menubar.set_icon_theme("theme name")

You should also add a key combination to trigger the menu. Find the place in rc.lua where the globalkeys are defined and add this line:

 awful.key({ modkey }, "s", function () end),


Walking through all files in the shortcut directories can take a noticeable amount of time (it takes up to 1 second on my machine). That may be rather annoying if you use menubar often (and on slower machines it can be even longer), so the entries caching option is enabled by default. It means that when launched the first time menubar parses .desktop files and keeps them in memory. This makes the consequent uses of menubar instant. The drawback is that you need to update menubar manually when new software is installed. You can do this by calling menubar.refresh() from Run Lua code prompt (Modkey-X by default).


  • Left/Right or Control-J/K - move through entry list
  • Return - launch highlighted application or enter the highlighted category
  • Escape - exit category (if inside one) or close the menubar
  • Backspace - if no text is entered exit the category

All other key combinations are the same as in awful.util.prompt.


You can change the category list by editing menu_gen.lua. Each category is a table with the following fields:

  • name - how the category should be displayed
  • app_type - the category name that appears in the Category tag in .desktop files
  • icon - icon of the category, could be either a full path to the file or just the name of the file to be found in default icon folders (like /usr/share/icons/)
  • use - if false, the category (and all applications from it) will be ignored

You can use a few lines like below to change names without editing menu_gen.lua (the example is Hungarian).

local menubar_change = {
     AudioVideo = "Média",
     Development = "Fejlesztés",
     Education = "Oktatás",
     Game = "Játékok",
     Graphics = "Grafika",
     Office = "Iroda",
     Network = "Hálózat",
     Settings = "Beállítások",
     System = "Rendszer",
     Utility = "Eszközök",
for i,j in ipairs(menubar.menu_gen.all_categories) do
   menubar.menu_gen.all_categories[i].name = 
       menubar_change[j.app_type] or

You can also change where the menubar pops up, as well as the menubar's size:

menubar.g = {
   height = 30,
   width = 600,
   x = 0,
   y = 700