Skip to content

App Settings

The [app] section controls core EasyBar runtime behavior.

Example:

[app]
show_menu_bar_icon = true
widgets_dir = "~/.config/easybar/widgets"
lua_path = "lua"
runtime_dir = "~/.local/state/easybar/runtime"
watch_config = true
widget_editor_stub_path = "~/.local/share/easybar/easybar_api.lua"
develop = false

show_menu_bar_icon

Controls the persistent EasyBar controller icon in the macOS menu bar.

[app]
show_menu_bar_icon = true

The icon is enabled by default and provides runtime controls even while the EasyBar bar is stopped. Set it to false when you do not want the additional menu bar item.

See Runtime Control for the available actions and recovery behavior.

widgets_dir

The directory where EasyBar loads Lua widget files from.

[app]
widgets_dir = "~/.config/easybar/widgets"

Every regular *.lua file directly inside this directory is loaded by the Lua runtime. Files below the lib/ subdirectory are available through standard Lua require(...) calls and are not started as widgets.

If you are creating your first custom widget, continue with First Widget. For shared helper code, see Reusable Modules.

lua_path

The Lua executable used for the Lua widget runtime.

[app]
lua_path = "lua"

The default value lua is resolved through PATH. Use an absolute path only when you want to pin a specific Lua installation.

runtime_dir

The base directory for EasyBar's runtime sockets and lock files.

[app]
runtime_dir = "~/.local/state/easybar/runtime"

By default, EasyBar derives these paths from runtime_dir:

easybar.sock
lua-runtime.sock
calendar-agent.sock
network-agent.sock

The main-app lock directory also defaults to runtime_dir.

EASYBAR_RUNTIME_DIR is a real environment override for this setting. It takes precedence over app.runtime_dir.

lua_socket_path

Optional dedicated Unix socket override for communication between the main app and the Lua widget runtime.

[app]
lua_socket_path = "/custom/runtime/lua-runtime.sock"

When omitted, EasyBar uses lua-runtime.sock inside runtime_dir.

This socket is separate from stderr logs. Runtime protocol messages use JSON over the Lua socket.

See Runtime Control and Lua Runtime Overview.

watch_config

Controls whether EasyBar watches config.toml and reloads automatically when the file changes.

[app]
watch_config = true

When this is false, update the running app manually after config edits:

easybar config reload

lock_dir

Optional override for the directory used by EasyBar runtime lock files.

[app]
lock_dir = "/custom/runtime/locks"

When omitted, the lock directory is runtime_dir. The lock is part of the single-instance guard that prevents multiple EasyBar app processes from drawing duplicate bars.

widget_editor_stub_path

Path where EasyBar keeps the combined LuaLS/editor stub in sync for widget authoring.

[app]
widget_editor_stub_path = "~/.local/share/easybar/easybar_api.lua"

Point your Lua language server workspace at this file to get autocomplete and diagnostics for the public EasyBar Lua API.

See Editor Support.

develop

The hidden developer menu section can be shown without holding Shift with:

[app]
develop = true

By default, the developer section is hidden unless you hold Shift and right-click the bar.

See Developer Menu.

lua_commands

Command execution limits for easybar.exec(...) and easybar.exec_async(...).

[app.lua_commands]
timeout_seconds = 5
max_output_bytes = 65536
max_async_jobs = 8
  • timeout_seconds: default hard timeout for one command before EasyBar terminates it. Widgets can override this per easybar.exec(...) or easybar.exec_async(...) call.
  • max_output_bytes: default maximum combined stdout and stderr captured for one command. Widgets can override this per call.
  • max_async_jobs: maximum concurrent easybar.exec_async(...) jobs before new jobs are rejected.