Updating and removing Buttons work differently enough across Windows, macOS, and Linux that it's worth understanding each before you do either. There's no auto-update on any platform: every update is a manual reinstall or re-extraction.
Before you begin#
- Know which platform you're on: the update and removal mechanics genuinely differ, not just cosmetically.
- Quit Buttons normally before updating or uninstalling. On Windows in particular, this matters more than it might seem: see below.
How updates actually work#
There's no self-update mechanism: Buttons only checks for and displays a notice that a new version exists; it never downloads or installs anything for you. Updating means running the new installer (Windows/macOS) or extracting the new release over a fresh location (Linux) yourself.
Every version stores its configuration in its own separate, version-named database. The practical effect: the first time you run a new version (even a small update) it detects that its own database doesn't exist yet and offers you a choice: import a copy of an earlier version's configuration, or start with an empty one. Importing makes a copy for the new version; it does not modify or touch the version you're upgrading from. This is a real, explicit choice you make, not something that happens silently in the background.
Note
You can't import a configuration from a version newer than the one you're currently running; that option is unavailable in the picker.
Update or remove on Windows#
Buttons ships a full installer and uninstaller (NSIS-based) on Windows.
- Updating: run the new installer over the existing installation.
- Uninstalling: use the uninstaller from Add or remove programs. It removes the application files, shortcuts, and the firewall rules the installer added, but it does not remove your data. Your configuration and database live in a separate location the uninstaller never touches, so removing Buttons this way doesn't delete your existing configuration.
Warning
The Windows uninstaller stops Buttons by force-terminating it directly, not by asking it to shut down gracefully. Always quit Buttons normally yourself (from its own interface) before running the uninstaller or a new installer over an existing install, rather than relying on the uninstaller to close it cleanly for you.
As a safety net for when that doesn't happen, the installer itself also stops any leftover PostgreSQL, Redis, or Garnet process it finds still running from a previous install, once you've confirmed the install and before files are copied. It only targets processes running from the previous or destination install path, not an unrelated system-wide PostgreSQL or Redis you might have installed separately.
If some files can't be removed immediately (for example, because they're still in use), the uninstaller tells you a restart is needed to finish removing them: this is expected, not a failure.
Update or remove on macOS#
Buttons ships a signed, notarized .pkg installer on macOS, but there's no uninstaller at all.
- Updating: run the new
.pkg installer. If Buttons is currently running, the installer detects this and prompts you to quit it before continuing; quit it yourself from the app rather than waiting on the prompt to force anything. - Uninstalling: remove
Bitfocus Buttons from your Applications folder manually. If you also want to remove your configuration and database, delete the app's folder under your user Library's Application Support directory as well; the installer leaves this decision entirely to you, since nothing automates it.
Update or remove on Linux#
- Updating: extract the new release, following the same setup steps as a fresh install. Stop the running service first (
sudo systemctl stop bitfocus-buttons if you set it up as a service) before replacing the files. - Uninstalling: stop and remove the systemd service if you configured one, then delete the extracted directory yourself. Nothing does this for you automatically.
Where your data actually lives#
Your database, configuration, modules, and logs live in a separate location from the application files on every platform: this is why updating or uninstalling doesn't wipe your configuration by default. The exact location differs per OS; if you need to find it directly (for backup, inspection, or manual cleanup), check your platform's application-data conventions rather than looking inside the folder where Buttons itself is installed.
Rollback#
There's no formal "roll back to the previous version" button. In practice, though, reinstalling an older version's installer isn't blocked, and since each version's database is a separate, untouched copy, reinstalling an older version can reconnect you to that version's own still-intact configuration, as long as you haven't since imported it into something newer. Treat this as a useful fact about how versioning works, not a guaranteed or officially supported rollback feature. For a real, deliberate way back to a known-good state, use
Restore a backup and verify it instead.
If you get stuck#
What you see | What to try |
|---|
A new version's first launch asks you to pick a configuration to import. | This is expected: pick the version you want to bring forward, or start empty. Importing copies the data; it doesn't touch the source version. |
You can't import from a specific older version. | You can only import from versions older than the one you're currently running, never newer. |
Buttons was left running when you uninstalled or updated on Windows. | Quit it yourself first next time: the Windows uninstaller stops it forcibly rather than gracefully, which can be avoided entirely by closing Buttons normally beforehand. |
You uninstalled Buttons on Windows but it still shows past configuration when reinstalled. | Expected: uninstalling on Windows never removes your data directory. Remove it yourself if you actually want a clean slate. |
You want to fully remove Buttons and its data on macOS. | There's no uninstaller: delete the app from Applications, and separately delete its Application Support folder if you want your data gone too. |
You're reinstalling on Linux and want a truly clean start. | Delete the old extracted directory (and its data location) yourself before extracting the new release: nothing automates this. |
A Linux update seems to conflict with a system-wide PostgreSQL or Redis. | Buttons runs its own PostgreSQL and Redis instances: make sure any system-wide services of the same kind are disabled, exactly as during initial setup. |
Where to go next#
