juhradial-mx

Install

Paste one line into a terminal as your normal user (not with sudo). The installer finds your distro, shows what it will change, and asks for sudo only for packages and system paths. It runs on these distributions and their derivatives:

curl -fsSL https://raw.githubusercontent.com/JuhLabs/juhradial-mx/master/install.sh | bash

Image-based systems install under ~/.local; sudo is used only for the udev rules, uinput and the input group (add --yes to skip the questions):

curl -fsSL https://raw.githubusercontent.com/JuhLabs/juhradial-mx/master/install.sh | bash -s -- --user

Try it without installing (the NixOS module is under Other ways to install):

nix run github:JuhLabs/juhradial-mx

If the installer adds you to the input group, log out and back in once. Minimal systems may need curl first (sudo apt install curl on Debian and Ubuntu). Coming from 0.4.4? Run the same line again; Upgrading from 0.4.4 has the details.

Other ways to install

The .deb and .rpm install the program, udev rules and user service, but not the per-user setup the installer does. After installing one, add yourself to the input group (sudo usermod -aG input $USER), log out and back in, run systemctl --user enable --now juhradialmx-daemon, then start juhradial-mx. GNOME needs the cursor helper extension, which only the one-line installer sets up, so GNOME users should prefer the installer. The installation guide covers requirements, manual setup per distro and NixOS.

What’s new since 0.4.4

Added

• A new Settings app built with Qt/QML: frosted glass cards, twelve colour themes with matched wallpapers, search across every setting and 18 languages. It runs on Qt 6.4 and newer; the GTK app stays as the fallback below that.
• MX Keypad support: nine display keys with pages, per-app profiles, key art, folders, two-state keys, text keys and shareable packs.
• MX Keys S support (opt-in, beta): battery, backlight, Easy-Switch follow and key remapping.
• Directional gestures: drag the gesture button up, down, left or right for four more actions (#146).
• Deeper MX Master 4 haptics: four strength levels, the Sense Panel press force and a pattern for each event.
• Custom actions on any button, per-app buttons, macros that record and play back on Wayland, gaming mode, plugins, and a one-zip backup of your whole setup.
• More ways to install: .deb and .rpm downloads, install.sh --user for Bazzite and Fedora Atomic (#138), a NixOS module (#9) and a native radial menu on niri (#22).

Improved

• Per-app profiles override only what you change and can have their own ring.
• Easy-Switch shows every computer slot and can take the MX Keys S along.
• Point & Scroll follows the mouse’s real DPI range, and your settings come back after a wake or a trip to another computer.
• The menu opens faster with less HID++ traffic; quieter battery polling (#90) and batched thumb-wheel actions (#97) by @frizikk.
• Flow only talks to computers you have approved.

Fixed

• The ring highlights the right slice on scaled displays (#147, fixed by @iceteaSA in #145).
• The menu opens at the cursor on GNOME 51 (#144).
• The radial menu starts at login, and scroll speed works on KDE Plasma Wayland.
• Middle, Back and Forward remaps send real mouse buttons, and the Copy, Paste and Undo slices work.
• Haptics, battery and DPI keep working after an Easy-Switch trip, and Bluetooth mice no longer lag.
• The charging state is read correctly for the mouse and the keyboard.

The full list, with credits and issue links, is in the changelog.

What it is

JuhRadial MX is a native Linux companion for Logitech MX devices. A small Rust daemon talks HID++ to the hardware, a PyQt6 overlay draws the radial menu at your cursor, and the new Qt/QML Settings app configures everything: buttons, gestures, haptics, scrolling, per-app profiles, Easy-Switch, the MX Keypad’s display keys and the MX Keys S backlight. The MX Master 4 gets the full feature set, including its haptic motor; the MX Master 3S and 3 use every control they expose, and most other mice can use generic mode for extra-button remapping.

_{The new Settings app: click a button on the mouse to reassign it, click a slice of the Actions Ring to edit it}

Highlights

Mouse (MX Master 4, 3S and 3)

• Actions Ring: hold (or tap) a button and pick one of eight actions under your cursor. A slice can run a shortcut, app, command, link, macro or plugin action; Pick application on every slice and on each Quick links row lists your installed apps and puts the app’s real icon on the ring. Ring size, centre zone and icon size are adjustable, or sized automatically per monitor.
• Button remapping: every button, plus every other control the mouse reports, can carry a shortcut (F13 to F24 included), app, command, link, macro, real mouse buttons, DPI steps, Easy-Switch targets and more. Edit for all apps, for this mouse only, or for one app profile.
• Directional gestures: hold the gesture button and drag up, down, left or right for four more actions, while a plain press keeps its own action.
• Haptics per event (MX Master 4): four strength levels, the Sense Panel press force, and a switch and pattern for each event: menu open, slice change, action, empty slice, gesture threshold, DPI change, macros, low battery, the mouse returning from another computer, app switch and monitor switch. They live in Settings → Haptics, Events card; App switch and Monitor switch are in its Desktop group. Haptics can mute while gaming or while chosen apps are in front.
• Point & Scroll: DPI follows the range the mouse reports, SmartShift, ratchet or free-spin, scroll force, hi-res and natural scrolling, and a thumb wheel for volume, zoom or horizontal scroll. Settings are replayed after a wake, a reconnect or a trip to another computer.
• Easy-Switch: see each computer slot, name this computer, and switch with a confirmation that tells you how to come back.

_{Haptics: one switch and one pattern per event, previewed on hover}

MX Keypad

• Nine display keys with icons and labels, pages you flip with the two page buttons, and ready templates (Everyday, Media, Developer, Meetings).
• Pages per app: pages that come up by themselves while an app is in front, with ready profiles for browsers, editors and IDEs, terminals, media players, video calls, creative tools, office suites and chat apps, plus profiles for AI coding tools. Settings suggests the ones that match the apps on your computer.
• Folders and two-state keys: a key can open a folder page, or switch between two states (like a mute toggle). Keys can also jump to a page by name.
• Key art and animation: a gallery of key art in two styles, any app icon, a glyph, your own picture, or an animated GIF or WebP. Each key has its own colour and can hide its label.
• Text keys and push to talk: paste a text or prompt with the exact characters on any keyboard layout, or hold a shortcut down for as long as the key is held.
• Packs: save a group of pages as a pack and import packs, pictures and labels included.
• Blank on screen lock: while the screen is locked the keys go dark and do nothing, so a text key never types into the lock screen.

_{MX Keypad: the key plates as they look on the device, with the key editor beside them}

MX Keys S (opt-in)

• Battery and backlight: battery level on the Dashboard and the Devices page, the backlight level and mode read back from the keyboard, and the keyboard’s own backlight keys reflected in Settings right away.
• Easy-Switch follow: “Mouse and keyboard move together” sends the keyboard to the same computer as the mouse, and pressing an Easy-Switch key on the keyboard takes the mouse along.
• Key remapping: rewrite keys (CapsLock to Ctrl and friends) through a virtual keyboard. Keyboard support is off by default and marked beta.

Settings app and look

• Redesigned Settings: the GTK app is replaced by a Qt/QML app with frosted glass cards, real product photos with clickable callouts, a Dashboard with live device state, search across every setting (Ctrl+K), keyboard navigation, and Simplified and Generic mouse quick switches in the header.
• Twelve colour themes, each with a matched wallpaper (Azure, Sky, Indigo, Violet, Emerald, Teal, Cyan, Brass, Amber, Coral, Rose, Magenta), a gallery of wheel skins, four icon styles, hover previews on the ring, and Reduce transparency for solid cards.
• Tray: the tray tooltip names the mouse, its battery, the Easy-Switch host and the active profile, with a low-battery notice.

_{Themes: twelve accents with matched wallpapers, and wheel skins picked separately}

Profiles, automation and more

• Per-app profiles that override only what you change, with their own buttons and their own ring. Try now applies a profile for a minute as if its app were in front, and Settings offers a profile the first time a new app takes focus.
• Macros: record from any keyboard and mouse, edit the steps, bind a trigger, and play back on Wayland and X11.
• Gaming mode: DPI presets, a hidden ring in games, a locked wheel mode, and an automatic mode that turns on while GameMode runs a game.
• Flow: move the cursor and clipboard to another computer on your network. New computers must be approved once in Settings → Flow; hold Ctrl to cross, send the cursor now, and identify screens. See JuhFlow.
• Plugins: a folder with a plugin.json adds actions to the slice picker. See the plugins guide.
• Backup: Settings → Settings → Backup exports your whole setup (config, profiles, macros, icons, themes) to one zip and imports it on this or another computer. Flow pairing keys never leave the machine.

The full list, with credits and issue links, is in the changelog.

Supported devices and desktops

Devices

Bolt, Unifying and Bluetooth connections are supported, including two receivers on one machine.

Desktops

Known limits, workarounds and what is being worked on

• Per-app profiles on GNOME, COSMIC, sway and niri. Per-app profiles, app-switch haptics and MX Keypad app pages only see XWayland apps there, because these desktops do not tell other programs which native Wayland window has focus. Workaround: start the app under XWayland, for example with --ozone-platform=x11 for Chromium and Electron apps or QT_QPA_PLATFORM=xcb for Qt apps. Being worked on: reading the focused window through the desktops’ own interfaces (the GNOME helper extension, sway and niri IPC).
• Monitor-switch haptic on COSMIC and niri. It can be missed or late, because the pointer position is only visible over XWayland windows there. Being worked on: following the desktop’s own active monitor where it offers one.
• niri without gtk4-layer-shell. The installer adds gtk4-layer-shell wherever the distro packages it, and the menu then opens at the pointer. Workaround where it is not packaged (for example openSUSE’s default repositories): run xwayland-satellite.
• MX Keypad on a locked screen. The keys go blank on lock on desktops that report the lock to logind, such as KDE Plasma and GNOME; on other desktops they stay active. Being worked on: more lock screens, such as swaylock and hyprlock.
• Settings on older Qt (Ubuntu 24.04, Linux Mint 22, Debian 12 and 13). The new Settings app runs on Qt 6.4 and newer. Below Qt 6.9 it draws solid cards and simpler shadows in place of the effects that Qt does not have yet; every page and control is there, the MX Keypad tab included. Below Qt 6.4 (for example Ubuntu 22.04) the previous GTK Settings app opens instead, without the MX Keypad tab; there juhradial-settings --keypad-template everyday gives a keypad its first page from a terminal.

See compositor support for the details per desktop.

Upgrading from 0.4.4

1. Optional: back up your setup with cp -r ~/.config/juhradial ~/juhradial-backup.
2. Re-run the same one-line command (with --user if you installed that way). Your configuration is kept; new settings start at their defaults.
3. On GNOME, log out and back in once so the updated cursor helper loads (it now declares GNOME 45 to 51).
4. Open Settings. It is now the new Qt app. If your Qt is older than 6.4, the GTK app opens as before; JUHRADIAL_SETTINGS=gtk juhradial-settings forces it.
5. If you use Flow, approve your other computer once in Settings → Flow. Computers you have not approved no longer receive the clipboard or control the cursor.
6. If the MX Keypad is not found right after the upgrade, unplug it and plug it back in so the new device rules apply.

Configuration and docs

Settings writes everything to:

~/.config/juhradial/config.json

The daemon reloads it when Settings saves, so there is nothing to restart. The same backup that Settings makes is available from the command line:

juhradiald --export ~/juhradial-backup.zip
juhradiald --import ~/juhradial-backup.zip

The running service answers from a terminal or a script as well:

juhradial-mx status          # mouse, battery, DPI and computer slot (--json for scripts)
juhradial-mx doctor          # what is wrong with this install, and the fix for each point
juhradial-mx dpi 1600        # also: host 2, keypad-page 3, reload

Languages

Settings is available in English and 18 more languages: Arabic, Chinese (Simplified), Dutch, French, German, Hindi, Italian, Japanese, Korean, Norwegian Bokmål, Polish, Portuguese (Brazil), Russian, Spanish, Swedish, Thai, Turkish and Ukrainian. It follows your desktop’s language by default; Settings → Language picks another one. Corrections from native speakers are welcome as issues or pull requests.

JuhFlow

JuhFlow moves the cursor and clipboard between Linux and macOS over the local network, with no cloud account or relay.

_{macOS companion disk image}

Troubleshooting

Settings → Settings has a troubleshooting card with the service and overlay status, a restart button, the log and Report a bug. For verbose daemon output:

journalctl --user -u juhradialmx-daemon -f

See the troubleshooting guide for more.

Uninstall

# 1. Stop and disable the JuhRadial user service
systemctl --user disable --now juhradialmx-daemon.service
rm -f ~/.config/systemd/user/juhradialmx-daemon.service

# Only run these two lines if JuhRadial created this user unit
systemctl --user disable --now ydotoold.service
rm -f ~/.config/systemd/user/ydotoold.service

systemctl --user daemon-reload

# 2. Remove the autostart entry
rm -f ~/.config/autostart/juhradial-mx.desktop

# 3. Remove binaries, assets, desktop entries, and the icon
sudo rm -f  /usr/local/bin/juhradiald \
            /usr/local/bin/juhradial-mx \
            /usr/local/bin/juhradial-settings
sudo rm -rf /usr/share/juhradial /opt/juhradial-mx
sudo rm -f  /usr/share/applications/juhradial-mx.desktop \
            /usr/share/applications/org.kde.juhradialmx.settings.desktop \
            /usr/share/icons/hicolor/scalable/apps/juhradial-mx.svg

# 4. Remove udev rules and uinput module configuration, then reload
sudo rm -f  /etc/udev/rules.d/99-juhradialmx.rules \
            /etc/udev/rules.d/70-juhradialmx-uaccess.rules \
            /etc/udev/rules.d/60-ydotool-uinput.rules \
            /etc/modules-load.d/juhradial-uinput.conf
sudo udevadm control --reload-rules && sudo udevadm trigger

# 5. Remove user configuration
rm -rf ~/.config/juhradial

gnome-extensions disable [email protected]
rm -rf ~/.local/share/gnome-shell/extensions/[email protected]

A user-mode install (--user) is removed with the steps in the installation guide. Packages are removed with your package manager.

Architecture

See docs/architecture.md for the component boundaries and data flow.

Contributing, conduct and security

Contributions are welcome: code, translations, hardware reports and testing on desktops we do not run every day. Read CONTRIBUTING.md for the development setup and pull request guidelines.

Everyone taking part is expected to follow the Code of Conduct.

Please report security issues privately as described in the security policy, not in public issues.

Credits

JuhRadial MX is maintained by JuhLabs with co-maintainer @gcarmin, who designed and built the application picker (#117, #118), the app-switch, monitor-switch and submenu haptics (#119, #120, #122), the adjustable ring size (#137) and the MX Master 3/3S layout with real device names (#136), and diagnosed the Bluetooth reconnect loop (#124).

Thanks to everyone who contributed to this release:

• @iceteaSA: the ring geometry fix for scaled displays (#145), and the directional gestures request and config layout (#146, #148).
• @frizikk: quieter battery polling (#90) and batched thumb-wheel actions (#97), following the 0.4.3 performance work.
• @FoxQwartz: the hardware-level SmartShift, hi-res scroll and Devices reports behind 0.4.4 (#106, #107, #108).
• @sandking1101: the Bazzite user-mode request and the slow-login diagnosis (#138).
• @sndev28: confirming the Bluetooth reconnect loop on hardware (#126).
• @TomiEckert (niri, #22), @GarrettGR (NixOS module, #9), @LightOSproblems (ring scaling), @YacineSahli (#127) and @Addonis-13 (#128, #129) for their requests and reports.

Every contribution is credited where it landed in the changelog.

License

JuhRadial MX is licensed under the GNU General Public License v3.0. The crates/mx-keypad protocol crate is available under MIT or Apache-2.0.

Star history

If JuhRadial MX is useful to you, a star helps other Linux users find the project.

Trademark notice

JuhRadial MX is not affiliated with, endorsed by, or associated with Logitech. Logitech, MX Master, MX Keys, MX Keypad, Logi Options+, and related names are trademarks of Logitech International S.A. Distribution names and logos belong to their respective projects and appear only to say where JuhRadial MX runs. This is an independent, community-built open-source project.

Maintained by JuhLabs

Report a bug  ·  Request a feature  ·  Discussions