Everything your Logitech mouse can do — on Linux, on Wayland.
Remap every button, hold and move for gestures, tune SmartShift and the thumb wheel,
and give every application its own setup. Native on KDE Plasma, Hyprland, Sway and GNOME.
Logitech's Options+ never came to Linux. The existing tools are great at what they do — Solaar for device settings, logiops for a config-file daemon — but none of them gives you the whole experience: a polished app where you click a button on a picture of your mouse, pick what it should do, and it just works, including gestures and per-application settings, on a modern Wayland desktop.
Mouse Master is that app.
- Every button, any action. Built-in actions (overview, desktops, media, windows, tabs, zoom, screenshots…), keyboard shortcuts recorded with one press, mouse buttons, commands, apps, websites and files, pointer speed and Easy-Switch. Keys are held while you hold the button, so modifier combos and drag-and-drop work.
- Mouse gestures on any capable button. Hold the gesture button (or the middle, back, forward or mode shift button) and move: up, down, left, right, or just click. Presets for desktop navigation, media, windows and the browser; repeat while moving for volume; pan mode — move the mouse to scroll in any direction; or zoom mode — move it up and down to zoom.
- Per-application profiles. Customize buttons, gestures, the thumb wheel and even pointer speed for a single app. Switching is automatic and instant on KDE Plasma (KWin), Hyprland and Sway.
- Thumb wheel superpowers. Horizontal scrolling at your speed, or zoom, volume, brightness, tabs, desktops, undo/redo — or any two actions of your choice. Tap the wheel for one more.
- Smooth pinch zoom. The thumb wheel and zoom gestures zoom around the pointer like a touchpad pinch, in browsers, document and image viewers and maps.
- Pointer & scroll. DPI with presets, a cycle action and a hold-for-precision mode. SmartShift on/off and sensitivity, ratchet or free spin, torque (MX Master 4), smooth high-resolution scrolling and natural scrolling, all in the device itself.
- Live. Press a button on the mouse and it lights up in the app. Hold the gesture button and watch your gesture being drawn.
- Easy-Switch, battery and haptics. See and rename the computers your mouse is paired with, switch to another one, get a notification when the battery runs low, and tune the MX Master 4's haptic feedback.
- Bluetooth, Bolt, Unifying and Lightspeed. Settings follow the device, whichever way it is connected, and are applied again whenever it wakes up or reconnects.
- Light and polite. A Rust service that uses less than 10 MB of memory and no CPU while idle, a Qt 6 app you only open to change things, a D-Bus API and a CLI. It never changes a setting you did not touch, and puts every button back to normal when it stops.
![]() |
![]() |
![]() |
![]() |
![]() |
|
![]() |
![]() |
git clone https://github.com/burakgon/mouse-master-linux
cd mouse-master-linux/packaging/arch && makepkg -si
systemctl --user enable --now mouse-master.serviceYou need Rust (1.85+), CMake, a C++ compiler and Qt 6.5 or newer:
| Distribution | Packages |
|---|---|
| Arch, CachyOS, Manjaro | sudo pacman -S --needed rust cmake qt6-base qt6-declarative qt6-svg qt6-wayland |
| Fedora | sudo dnf install cargo cmake gcc-c++ qt6-qtbase-devel qt6-qtdeclarative-devel qt6-qtsvg-devel systemd-devel |
| Debian 13, Ubuntu 24.10+ | sudo apt install cargo cmake g++ libudev-dev qt6-base-dev qt6-declarative-dev qt6-svg-dev qt6-wayland qml6-module-qtquick-controls qml6-module-qtquick-layouts qml6-module-qtquick-shapes qml6-module-qtquick-effects qml6-module-qtquick-dialogs qml6-module-qtcore |
| openSUSE Tumbleweed | sudo zypper install cargo cmake gcc-c++ qt6-base-devel qt6-declarative-devel qt6-svg-devel systemd-devel |
Then:
git clone https://github.com/burakgon/mouse-master-linux
cd mouse-master-linux
./scripts/install.sh # installs to /usr/local, sets up device access and the service./scripts/install.sh --uninstall removes it again (your settings stay in ~/.config/mouse-master).
Note
Mouse Master needs access to your Logitech devices and to /dev/uinput. The installer adds a
udev rule that grants both to the user sitting at the computer — no root daemon, no input
group. If you install another way, the app offers to set this up for you.
The service is a systemd user unit started at login (default.target), so it works without a
systemd-managed session. If your setup does not use systemd at all, start it yourself:
# ~/.config/hypr/hyprland.conf
exec-once = mouse-masterd| KDE Plasma | Hyprland | Sway | GNOME | X11 | |
|---|---|---|---|---|---|
| Buttons, gestures, thumb wheel, keys, scrolling | ✅ | ✅ | ✅ | ✅ | ✅ |
| Desktop actions (overview, desktops, windows) | ✅ native | ✅ dispatchers | ✅ | ✅ shortcuts | |
| Per-application profiles | ✅ | ✅ | ✅ | — | — |
| On-screen display for DPI and wheel mode | ✅ Plasma OSD | notification | notification | notification | notification |
Desktop actions use each desktop's own mechanism: KWin's global shortcuts on Plasma, IPC
dispatchers on Hyprland (Overview uses the hyprexpo plugin when present), swaymsg on Sway.
Mouse Master speaks Logitech's HID++ 2.0 protocol and discovers what each device can do, so it works with far more mice than it has artwork for.
| Device | Status |
|---|---|
| MX Master 3S | ✅ tested (Bluetooth) |
| MX Master 4 | ✅ tested (Bluetooth), including haptics and SmartShift torque |
| MX Master 2S, MX Master 3 / 3 for Mac / 3S for Mac | expected to work — same features as the 3S |
| MX Anywhere 2S / 3 / 3S, MX Vertical, MX Ergo, Lift, M720, M590, Signature M650 | expected to work |
| G series over Lightspeed or USB | DPI, report rate and onboard memory; buttons where the mouse allows remapping |
| Bolt, Unifying, Lightspeed and Nano receivers | ✅ (receiver handling is covered by the test suite) |
Got one of these? Run mouse-masterctl info and let us know
how it went — it helps others and lets us add artwork for your mouse.
$ mouse-masterctl list
● MX Master 3S b034-1A2B3C4D battery 65%
$ mouse-masterctl set dpi=1600 smartshift=true smartshift_threshold=12
$ mouse-masterctl bind back copy # a built-in action
$ mouse-masterctl bind forward '{"type":"keys","keys":["KEY_LEFTCTRL","KEY_T"]}'
$ mouse-masterctl bind gesture gestures # gestures with the default set
$ mouse-masterctl actions # every built-in action on this desktop
$ mouse-masterctl monitor # watch buttons, gestures and focus changesSettings live in ~/.config/mouse-master/config.toml. The app writes it for you, but it is
meant to be readable and editable (stop the service while you edit it):
[devices."b034-1A2B3C4D"]
name = "MX Master 3S"
[devices."b034-1A2B3C4D".settings]
dpi = 1600
dpi_presets = [800, 1600, 3200]
smartshift = true
smartshift_threshold = 12
[devices."b034-1A2B3C4D".bindings.buttons.gesture]
type = "gestures"
up = { type = "builtin", id = "overview" }
down = { type = "builtin", id = "show-desktop" }
left = { type = "builtin", id = "workspace-left" }
right = { type = "builtin", id = "workspace-right" }
click = { type = "builtin", id = "overview" }
[devices."b034-1A2B3C4D".bindings.buttons.back]
type = "keys"
keys = ["KEY_LEFTCTRL", "KEY_Z"]
[[devices."b034-1A2B3C4D".profiles]]
id = "p1"
name = "Firefox"
apps = ["firefox", "org.mozilla.firefox"]
bindings.buttons.forward = { type = "builtin", id = "reopen-tab" }See docs/configuration.md for every option.
Logitech mouse ──HID++ over hidraw──▶ mouse-masterd ──uinput──▶ your compositor
(Bluetooth / receiver) │ ▲ │
│ │ └── KWin / Hyprland / Sway: focused app,
D-Bus (session)│ │ desktop actions
▼ │
Mouse Master app, mouse-masterctl
The service diverts only the buttons you assign, so everything else keeps working natively, and it hands the buttons back when it stops. Gestures use the mouse's own raw motion reports while the button is held, so the pointer stays still. Actions are performed through uinput (keys, buttons, high-resolution scrolling, touchpad pinches for zoom) or the desktop's own API.
More in docs/architecture.md.
| Mouse Master | Solaar | logiops | Options+ | |
|---|---|---|---|---|
| Linux | ✅ | ✅ | ✅ | — |
| Graphical app | ✅ Qt 6 | ✅ GTK 3 | — | ✅ |
| Click-a-button remapping on device artwork | ✅ | — | — | ✅ |
| Mouse gestures | ✅ any capable button | via rules | ✅ | ✅ gesture button |
| Pan (drag to scroll) | ✅ | — | ✅ via axes | ✅ |
| Per-application profiles | ✅ automatic on Wayland | via rules (X11, GNOME) | — | ✅ |
| Thumb wheel actions + tap | ✅ | via rules | ✅ | ✅ |
| Receiver pairing | planned | ✅ | — | ✅ |
| Keyboards and lighting | planned | ✅ | partial | ✅ |
Solaar and logiops both divert buttons too: run only one of these tools at a time. Mouse Master warns you while one of them is running and applies your settings again once it quits.
- First step —
mouse-masterctl doctorchecks the device rules, access to every Logitech device and to/dev/uinput, the service, and tools that get in the way. - "Allow access to your devices" in the app — the udev rule is missing. Click Grant
access (asks for your password once), or install it by hand:
sudo install -m644 data/udev/70-mouse-master.rules /etc/udev/rules.d/ && sudo udevadm control --reload && sudo udevadm trigger. - A button does nothing after a crash — the service restarts automatically and fixes it; turning the mouse off and on also restores its native behaviour.
- Scrolling suddenly too fast or slow after toggling smooth scrolling — older kernels do not notice the change. Toggle it back or reconnect the mouse.
- A "Mouse Master virtual touchpad" in your input settings — that is how smooth zoom works: it pinches like two fingers on a touchpad. Leave it enabled; on KDE Plasma Mouse Master turns it back on if the touchpad toggle switched it off. Apps that ignore touchpad pinches still zoom with Ctrl + scroll: turn off Smooth zoom for the thumb wheel.
- Logs —
journalctl --user -u mouse-master -f, or runmouse-masterd -vin a terminal. - Try it without hardware —
mouse-masterd --demoruns on simulated devices.
cargo test --workspace # protocol, gesture engine and end-to-end tests
cargo run -p mouse-masterd -- --demo -v # the service on simulated devices
cmake -B build -DBUILD_SERVICE=OFF && cmake --build build && ./build/app/mouse-mastercrates/hidpp— async HID++ 1.0/2.0 for Linux hidraw, plus a device simulatorcrates/daemon—mouse-masterd: device actors, gestures, actions, profiles, D-Bus APIcrates/ctl—mouse-masterctlapp— the Qt 6 / QML app
Contributions are very welcome — see CONTRIBUTING.md. Device reports, artwork for more mice and translations are especially appreciated.
Mouse Master stands on the shoulders of the people who documented HID++: the Solaar and logiops projects, and Logitech's published HID++ documentation. Icons by Lucide (ISC).
GPL-3.0-or-later. See LICENSE.
Logitech, Logi, MX Master, MX Anywhere, Bolt, Unifying, Lightspeed, Easy-Switch and SmartShift are trademarks of Logitech. Mouse Master is an independent project and is not affiliated with, endorsed by, or sponsored by Logitech.






