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.5
Pages for other versions: 3.4.x


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. Default works only on Debian and is not very fancy. Another option is that parses directories for .desktop files and generates the menu from them. Still it is not fully 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 menu appears that contains all categories (defined in menu_gen.lua) and all applications. Typing the text will filter the entries in a way similar to dmenu - first come the entries which names match the text from the beginning, after them come entries that match the text in the middle of their names.

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

How to start[edit]

  • Menubar is already installed with your Awesome. The default keybinding for it is Modkey-P. You can search the default configuration file (/etc/xdg/awesome/rc.lua for it).
  • If you don't use the default configuration file then open your rc.lua file and add these lines:
 local menubar = require("menubar")
 -- Menubar configuration
 menubar.utils.terminal = terminal -- Set the terminal for applications that require it
  • By default menubar doesn't scan for local applications. To change the search path you can use something like this:
 menubar.menu_gen.all_menu_dirs = { "/usr/share/applications/", "/usr/local/share/applications", "~/.local/share/applications" }

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 }, "p", 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.


To customize the icon theme for the application icons add the following line in your theme.lua file:

 theme.icon_theme = "Humanity" -- Replace the string for the theme you want to use

You can change the category list by changing the table menubar.menu_gen.all_categories in runtime. Each category is a table with the following fields:

  • name - how the category would be displayed
  • app_type - the category name that appears in 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 (the example is hungarian): = "Média" = "Fejlesztés" = "Oktatás" = "Játékok" = "Grafika" = "Iroda" = "Hálózat" = "Beállítások" = "Rendszer" = "Eszközök"

Or you can turn off the categories you don't want to see (and applications from them respectively): = false = false

You can change the place for menubar to pop up and menubar's size too:

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