Repository navigation
Releases
BallKey 0.1.9: Fedora 43 and 45, Debian 13+, Arch
Works on more Linux versions
- Fedora 43 and 45: the update repository now has BallKey for Fedora 43, 44 and 45. If you upgraded to Fedora 45 and
dnf updatefailed with a "404" error for the BallKey repository, that's fixed: just run it again. - Supported versions: Fedora 43 and later, Debian 13 and later (and Debian-based distributions with PySide6), and Arch Linux (tested back to January 2025). Debian 12 and Ubuntu 24.04 aren't supported, because they have no PySide6 package.
Nothing else changed since 0.1.8.
Install
| Distribution | File | Install |
|---|---|---|
| Fedora 43+ | ballkey-0.1.9-1.fc44.noarch.rpm |
Double-click it, or sudo dnf install ./ballkey-0.1.9-1.fc44.noarch.rpm |
| Debian 13+ and Debian-based | ballkey_0.1.9-1_all.deb |
sudo apt install ./ballkey_0.1.9-1_all.deb |
| Arch Linux | ballkey-0.1.9-1-any.pkg.tar.zst |
sudo pacman -U ballkey-0.1.9-1-any.pkg.tar.zst |
Fedora: if you installed 0.1.3 or later, Discover / Software and dnf upgrade will offer this update by themselves.
Debian-based: if you installed 0.1.6 or later, Discover / Software and sudo apt update && sudo apt upgrade will offer this update by themselves. If you have 0.1.5 or older, install this version by hand once.
Arch: automatic updates aren't available yet. They'll come through the AUR, but AUR account registration is currently down, so I can't publish BallKey there yet. For now, download and install new versions by hand.
Your settings and your "Start remapping at boot" choice are kept when you upgrade. SHA256SUMS lets you verify the downloads.
BallKey was vibecoded and is my first project; see the README for what that means and how it was tested. Bug reports and code review are very welcome.
BallKey 0.1.8: buttons that type keys in combinations
Buttons that type keys, improved
- In combinations: buttons that type a shortcut (like the Logitech G502's Ctrl+C and Ctrl+V buttons) can now be part of a button combination, together with mouse buttons or with each other. For example, Ctrl+C button + Ctrl+V button together = Middle click.
- G502 HERO: its two front buttons that type Ctrl+C and Ctrl+V from the factory now appear in the button list straight away, without clicking Identify button first. If you changed them with Piper, identify them again to add what they type now.
- Identify once: buttons you find with Identify button are remembered for each mouse, so they're still in the list (and in Add combination…) next time. Forget clears them.
If your mouse is listed as both a mouse and a keyboard, like the G502, a button that's missing from the list should appear after you click Identify button and press it. If it doesn't, please open a bug report with your mouse's name.
Install
| Distribution | File | Install |
|---|---|---|
| Fedora 44+ | ballkey-0.1.8-1.fc44.noarch.rpm |
Double-click it, or sudo dnf install ./ballkey-0.1.8-1.fc44.noarch.rpm |
| Debian-based | ballkey_0.1.8-1_all.deb |
sudo apt install ./ballkey_0.1.8-1_all.deb |
| Arch Linux | ballkey-0.1.8-1-any.pkg.tar.zst |
sudo pacman -U ballkey-0.1.8-1-any.pkg.tar.zst |
Fedora: if you installed 0.1.3 or later, Discover / Software and dnf upgrade will offer this update by themselves.
Debian-based: if you installed 0.1.6 or later, Discover / Software and sudo apt update && sudo apt upgrade will offer this update by themselves. If you have 0.1.5 or older, install this version by hand once.
Arch: automatic updates aren't available yet. They'll come through the AUR, but AUR account registration is currently down, so I can't publish BallKey there yet. For now, download and install new versions by hand.
Your settings and your "Start remapping at boot" choice are kept when you upgrade. SHA256SUMS lets you verify the downloads.
BallKey was vibecoded and is my first project; see the README for what that means and how it was tested. Bug reports and code review are very welcome.
BallKey 0.1.7: faster update checks on Fedora
Faster update checks on Fedora
Discover / Software and dnf upgrade now check BallKey's update repository every 6 hours (like Fedora's own updates) instead of every 48 hours, so new versions show up sooner.
Because 0.1.6 and older still check every 48 hours, this update itself can take up to two days to appear. To get it right away: sudo dnf upgrade --refresh ballkey.
Nothing else changed: the app works exactly like 0.1.6.
Install
| Distribution | File | Install |
|---|---|---|
| Fedora 44+ | ballkey-0.1.7-1.fc44.noarch.rpm |
Double-click it, or sudo dnf install ./ballkey-0.1.7-1.fc44.noarch.rpm |
| Debian-based | ballkey_0.1.7-1_all.deb |
sudo apt install ./ballkey_0.1.7-1_all.deb |
| Arch Linux | ballkey-0.1.7-1-any.pkg.tar.zst |
sudo pacman -U ballkey-0.1.7-1-any.pkg.tar.zst |
Fedora: if you installed 0.1.3 or later, Discover / Software and dnf upgrade will offer this update by themselves.
Debian-based: if you installed 0.1.6, Discover / Software and sudo apt update && sudo apt upgrade will offer this update by themselves. If you have 0.1.5 or older, install this version by hand once.
Arch: I'm working on automatic updates for Arch. For now, download and install new versions by hand.
Your settings and your "Start remapping at boot" choice are kept when you upgrade. SHA256SUMS lets you verify the downloads.
BallKey was vibecoded and is my first project; see the README for what that means and how it was tested. Bug reports and code review are very welcome.
BallKey 0.1.6: automatic updates on Debian-based distributions
Automatic updates on Debian-based distributions
The .deb now adds BallKey's signed update repository (hosted on GitHub Pages), so Discover / Software and sudo apt update && sudo apt upgrade find new versions by themselves, just like on Fedora.
If you have 0.1.5 or older, install this version by hand once (below). After that, updates come automatically.
Arch: I'm working on automatic updates for Arch too. For now, download and install new versions by hand.
Nothing else changed: the app works exactly like 0.1.5.
Install
| Distribution | File | Install |
|---|---|---|
| Fedora 44+ | ballkey-0.1.6-1.fc44.noarch.rpm |
Double-click it, or sudo dnf install ./ballkey-0.1.6-1.fc44.noarch.rpm |
| Debian-based | ballkey_0.1.6-1_all.deb |
sudo apt install ./ballkey_0.1.6-1_all.deb |
| Arch Linux | ballkey-0.1.6-1-any.pkg.tar.zst |
sudo pacman -U ballkey-0.1.6-1-any.pkg.tar.zst |
Fedora: if you installed 0.1.3 or later, Discover / Software and dnf upgrade will offer this update by themselves.
Your settings and your "Start remapping at boot" choice are kept when you upgrade. SHA256SUMS lets you verify the downloads.
The Debian update repository was tested in Debian 13 and Ubuntu 26.04 containers, not on real hardware.
BallKey was vibecoded and is my first project; see the README for what that means and how it was tested. Bug reports and code review are very welcome.
BallKey 0.1.5: wheel tilt and buttons that type keys
Wheel tilt
If your scroll wheel tilts left and right, Wheel tilt left and Wheel tilt right now appear in the button list, and you can give them any action (for example Back and Forward). Left on Default, tilting scrolls sideways as before.
Buttons that type keys
Some gaming mice, like the Logitech G502, have buttons that type a shortcut (for example Ctrl+C) instead of acting as mouse buttons. BallKey couldn't see these before. Now click Identify button and press one: it's added as "Button that types Ctrl+C", and you can give it any action. Left on Default, it keeps typing its shortcut. Your keyboard is never affected.
Buttons the mouse handles by itself, like the G502's DPI and sniper buttons, send nothing to the computer, so BallKey can't change them. For DPI and those buttons, use Piper, which works alongside BallKey.
Install
| Distribution | File | Install |
|---|---|---|
| Fedora 44+ | ballkey-0.1.5-1.fc44.noarch.rpm |
Double-click it, or sudo dnf install ./ballkey-0.1.5-1.fc44.noarch.rpm |
| Debian-based | ballkey_0.1.5-1_all.deb |
sudo apt install ./ballkey_0.1.5-1_all.deb |
| Arch Linux | ballkey-0.1.5-1-any.pkg.tar.zst |
sudo pacman -U ballkey-0.1.5-1-any.pkg.tar.zst |
Fedora: if you installed 0.1.3 or later, Discover / Software and dnf upgrade will offer this update by themselves.
Your settings and your "Start remapping at boot" choice are kept when you upgrade. SHA256SUMS lets you verify the downloads.
BallKey has been tested on real hardware (Fedora KDE) with a Logitech G502 HERO, Logitech G403 and Kensington Expert.
BallKey was vibecoded and is my first project; see the README for what that means and how it was tested. Bug reports and code review are very welcome.
BallKey 0.1.4: button combinations and more actions
Button combinations
Press several buttons together to do something else. For example, on a trackball without a middle button (like the Logitech Marble), set Left + Right to Middle click. Under the button list, click Add combination…, tick the buttons, and choose the action. The buttons still work on their own.
More actions
- Clicks: Double right click, Double middle click, and Left / Right / Middle drag: press once to hold the button down, move, then press again to let go. ("Double-click" is now called "Double left click".)
- Editing: Redo, Cut, Select all, Find (alongside Undo, Copy and Paste).
- Media: Play / pause, Stop, Next track, Previous track, Volume up, Volume down, Microphone on/off.
- Any keyboard key: "Custom key combo…" is now Keyboard key or combo…, and you can also pick keys from a list, for keys that aren't on your keyboard or that the desktop catches first.
Install
| Distribution | File | Install |
|---|---|---|
| Fedora 44+ | ballkey-0.1.4-1.fc44.noarch.rpm |
Double-click it, or sudo dnf install ./ballkey-0.1.4-1.fc44.noarch.rpm |
| Debian 13+, Ubuntu 26.04+ | ballkey_0.1.4-1_all.deb |
sudo apt install ./ballkey_0.1.4-1_all.deb |
| Arch Linux | ballkey-0.1.4-1-any.pkg.tar.zst |
sudo pacman -U ballkey-0.1.4-1-any.pkg.tar.zst |
Fedora: if you installed 0.1.3, Discover / Software and dnf upgrade will offer this update by themselves.
Your settings and your "Start remapping at boot" choice are kept when you upgrade. SHA256SUMS lets you verify the downloads.
BallKey was vibecoded and is my first project; see the README for what that means and how it was tested. Bug reports and code review are very welcome.
BallKey 0.1.3: Fedora updates through Discover
Fedora: automatic updates
BallKey now has an update repository on Fedora COPR: https://copr.fedorainfracloud.org/coprs/gino8807/ballkey/
- The Fedora package adds it for you, so Discover / Software and
dnf upgradefind new BallKey versions by themselves. If you installed 0.1.2, install this version once by double-clicking it; after that, updates arrive on their own. - The
.rpmis now built and signed by COPR. - You can also install straight from the repository:
sudo dnf copr enable gino8807/ballkey && sudo dnf install ballkey
Debian, Ubuntu and Arch: no changes for you in this version, apart from the version number. Download and install new versions by hand for now.
Install
| Distribution | File | Install |
|---|---|---|
| Fedora 44+ | ballkey-0.1.3-1.fc44.noarch.rpm |
Double-click it, or sudo dnf install ./ballkey-0.1.3-1.fc44.noarch.rpm |
| Debian 13+, Ubuntu 26.04+ | ballkey_0.1.3-1_all.deb |
sudo apt install ./ballkey_0.1.3-1_all.deb |
| Arch Linux | ballkey-0.1.3-1-any.pkg.tar.zst |
sudo pacman -U ballkey-0.1.3-1-any.pkg.tar.zst |
Your settings and your "Start remapping at boot" choice are kept when you upgrade. SHA256SUMS lets you verify the downloads.
BallKey was vibecoded and is my first project; see the README for what that means and how it was tested. Bug reports and code review are very welcome.
BallKey 0.1.2
First public release of BallKey, a simple graphical button remapper for any mouse or trackball on Linux.
Pick your device, choose what each button does (Back, Forward, Copy, Paste, Undo, Double-click, custom key combos, Do nothing, …), click Apply. Settings apply at every boot and when the device is reconnected. Works on Wayland and X11, with any brand.
Install
Download the file for your distribution below, then:
| Distribution | File | Install |
|---|---|---|
| Fedora 44+ | ballkey-0.1.2-1.noarch.rpm |
Double-click it, or sudo dnf install ./ballkey-0.1.2-1.noarch.rpm |
| Debian 13+, Ubuntu 26.04+ | ballkey_0.1.2-1_all.deb |
sudo apt install ./ballkey_0.1.2-1_all.deb |
| Arch Linux | ballkey-0.1.2-1-any.pkg.tar.zst |
sudo pacman -U ballkey-0.1.2-1-any.pkg.tar.zst |
Then open BallKey from your app menu. Ubuntu 24.04 isn't supported (no PySide6 package). SHA256SUMS lets you verify the downloads.
Features
- Identify button: press a button to find it in the list
- Custom key combos, recorded by just pressing them
- Lockout protection: if no button does a left click any more, the old settings come back after 15 seconds unless you confirm
- "Start remapping at boot" toggle
- "Forget" to remove a mouse you no longer have
- Changes ask for your password in the normal system prompt (polkit); no terminal needed
- If the service stops or crashes, your mouse goes straight back to normal
About this project
BallKey was vibecoded, and it's my first project: an AI coding assistant (Claude Code) wrote the code while I tested each step on Fedora KDE with a Logitech G403. The Debian, Ubuntu and Arch packages have only been tested in containers, not on real hardware, and no experienced Linux developer has reviewed it yet. Bug reports and code review are very welcome.
License: GPL-3.0-or-later.
BallKey 0.1.1 (older version)
Older version. For the newest BallKey, see the latest release. This one is kept for anyone who needs it.
- First version for Debian, Ubuntu and Arch (tested in containers).
- Fixes the background service not starting on Debian 13.
- Uninstalling removes all of BallKey's folders.
| Distribution | File | Install |
|---|---|---|
| Fedora 44+ | ballkey-0.1.1-1.noarch.rpm |
sudo dnf install ./ballkey-0.1.1-1.noarch.rpm |
| Debian 13+, Ubuntu 26.04+ | ballkey_0.1.1-1_all.deb |
sudo apt install ./ballkey_0.1.1-1_all.deb |
| Arch Linux | ballkey-0.1.1-1-any.pkg.tar.zst |
sudo pacman -U ballkey-0.1.1-1-any.pkg.tar.zst |
These packages were built afterwards (on 2026-10-18) from the saved 0.1.1 code. SHA256SUMS lets you verify the downloads.
BallKey 0.1.0 (older version, Fedora only)
Older version. For the newest BallKey, see the latest release. This one is kept for anyone who needs it.
The first version, for Fedora only: button remapping, the settings app, start at boot and reconnect handling.
Known problems, fixed in 0.1.1: uninstalling leaves an empty /usr/lib/ballkey folder behind, and the app may fail to open if systemd can't be reached. Debian, Ubuntu and Arch packages aren't offered for this version because the service doesn't start on Debian 13; use 0.1.1 or newer there.
Install: sudo dnf install ./ballkey-0.1.0-1.noarch.rpm
This package was built afterwards (on 2026-10-18) from the saved 0.1.0 code. SHA256SUMS lets you verify the download.