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
| Before | Now |
|---|---|
kwybars-daemon | kwybars |
kwybars-overlay | kwybars |
kwybarsctl validate-config | kwybars validate-config |
kwybarsctl doctor | kwybars doctor |
kwybarsctl list-themes | kwybars list-themes |
kwybarsctl switch-config | kwybars switch-config |
kwybarsctl image-overlay match | kwybars 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.tomlUser Service
The unit was renamed. If you used it:
systemctl --user disable --now kwybars-daemon.service
systemctl --user enable --now kwybars.serviceThe 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:
| Old | New |
|---|---|
[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:
| Old | New |
|---|---|
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:
| Key | Why |
|---|---|
[daemon] enabled, poll_interval_ms, stop_on_silence, overlay_command, overlay_args | There is no daemon and no second process to launch |
[daemon] notify_on_error, notify_cooldown_seconds | Desktop notifications were removed. Errors are in the log, and kwybars doctor explains setup problems |
[visualizer] backend | Audio always comes from PipeWire |
[visualizer] pipewire_attack, pipewire_decay, pipewire_gain, pipewire_curve, pipewire_neighbor_mix | Replaced 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 = 2200If 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 ofdaemon.logandoverlay.log. ./kwybars.tomlin the current directory is no longer looked for. Use--configorKWYBARS_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 matchedits 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-configkeeps a regular config file as<name>.bakbefore replacing it with a link, and stops when a different.bakalready exists.