Skip to Content
Kwybars
Usage

Upgrading from 0.2

What changed with the single kwybars binary and what to adjust.

Kwybars 0.3 is one program, kwybars. The daemon, the separate overlay process, and kwybarsctl are gone, and so are the Cava and GTK dependencies. Audio comes straight from PipeWire.

Your config keeps working. The steps below are about how you start Kwybars and a few settings that moved.

Commands

BeforeNow
kwybars-daemonkwybars
kwybars-overlaykwybars
kwybarsctl validate-configkwybars validate-config
kwybarsctl doctorkwybars doctor
kwybarsctl list-themeskwybars list-themes
kwybarsctl switch-configkwybars switch-config
kwybarsctl image-overlay matchkwybars image-overlay match

Update your compositor autostart line and any wallpaper hook scripts.

validate-config, doctor, and list-themes no longer take the config as a bare path. Use --config:

kwybars validate-config --config ~/.config/kwybars/custom/my_config.toml

User Service

The unit was renamed. If you used it:

systemctl --user disable --now kwybars-daemon.service
systemctl --user enable --now kwybars.service

The package upgrade removes the old programs and the old unit file by itself. The disable command above still works afterwards and clears the leftover link.

If you had an override for the old unit, create it again with systemctl --user edit kwybars.service and replace kwybars-daemon with kwybars in it.

Packages You No Longer Need

Cava, GTK4, gtk4-layer-shell, and libnotify were only needed by Kwybars 0.2. Remove them if nothing else on your system uses them.

Config Keys

These still load. Kwybars prints one warning for each group and carries on.

Moved keys, read from the old place until you move them:

OldNew
[daemon] activity_threshold[activity] threshold
[daemon] activate_delay_ms[activity] activate_delay_ms
[daemon] deactivate_delay_ms[activity] deactivate_delay_ms

Renamed keys for choosing monitors. The old ones still work and print a warning with the exact line to write instead:

OldNew
monitor_mode = "primary"show_on = "primary"
monitor_mode = "all"show_on = "all"
monitor_mode = "list" with monitors = ["DP-1"]show_on = ["DP-1"]
[[overlay.outputs]] with monitor = "DP-1"[output.DP-1]
Placement keys in [[overlay.outputs]], such as height[output.DP-1.overlay]
[overlay.outputs.visualizer][output.DP-1.visualizer]

One behavior differs with the new keys: show_on always decides which monitors are used, and [output.NAME] sections only adjust them. With the old keys, any [[overlay.outputs]] entry replaced the monitor list. Old configs keep the old behavior.

Removed keys, ignored:

KeyWhy
[daemon] enabled, poll_interval_ms, stop_on_silence, overlay_command, overlay_argsThere is no daemon and no second process to launch
[daemon] notify_on_error, notify_cooldown_secondsDesktop notifications were removed. Errors are in the log, and kwybars doctor explains setup problems
[visualizer] backendAudio always comes from PipeWire
[visualizer] pipewire_attack, pipewire_decay, pipewire_gain, pipewire_curve, pipewire_neighbor_mixReplaced by the [audio] section

To get rid of the warnings, delete the removed keys and rename [daemon] to [activity] with the new key names:

[activity]
threshold = 0.035
activate_delay_ms = 180
deactivate_delay_ms = 2200

If you tuned the pipewire_* keys, start from the [audio] defaults and adjust smoothing and sensitivity. The old values do not translate one to one.

Run kwybars validate-config to see exactly which keys in your file are affected.

Stricter Config Reading

The config is now read as real TOML. Two things that used to pass are errors:

  • the same key written twice in one section
  • a value of the wrong type, such as a number in quotes

kwybars validate-config names the file and the line.

Other Differences

  • An overlay image larger than the overlay area is no longer cut at its edge.
  • Logs go to one file, ~/.local/state/kwybars/kwybars.log, instead of daemon.log and overlay.log.
  • ./kwybars.toml in the current directory is no longer looked for. Use --config or KWYBARS_CONFIG.
  • The bars move a little differently. The spectrum is computed by Kwybars itself, not by Cava, so heights will not match the old version exactly.
  • kwybars image-overlay match edits the preset behind a config link only when the preset is in the same directory tree as the link. Otherwise it stops and tells you which file to name with --config.
  • kwybars switch-config keeps a regular config file as <name>.bak before replacing it with a link, and stops when a different .bak already exists.

On this page