echo 'deb http://download.opensuse.org/repositories/home:/mmaher88:/logitune/xUbuntu_24.04/ /' \
 | sudo tee /etc/apt/sources.list.d/logitune.list
curl -fsSL https://download.opensuse.org/repositories/home:mmaher88:logitune/xUbuntu_24.04/Release.key \
 | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/logitune.gpg > /dev/null
sudo apt update && sudo apt install logitune

sudo dnf config-manager addrepo --from-repofile=https://download.opensuse.org/repositories/home:mmaher88:logitune/Fedora_42/home:mmaher88:logitune.repo
sudo dnf install logitune

yay -S logitune

Or build from source:

bash scripts/package-arch.sh
sudo pacman -U logitune-*.pkg.tar.zst

Download from the Releases page:

# Ubuntu/Debian
sudo apt install ./logitune-VERSION_amd64.deb
# Fedora
sudo dnf install logitune-VERSION.rpm

Native packages automatically install udev rules and set device permissions — no manual udevadm steps needed. On GNOME, the Shell extension for focus tracking is also installed automatically.

See Building for full instructions. The short version:

git clone https://github.com/mmaher88/logitune.git
cd logitune
cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr
cmake --build build
sudo cmake --install build
logitune

Logitune needs read/write access to hidraw devices and uinput for keystroke injection. The udev rules file (data/71-logitune.rules) contains:

SUBSYSTEM=="hidraw", ATTRS{idVendor}=="046d", TAG+="uaccess"
KERNEL=="uinput", SUBSYSTEM=="misc", TAG+="uaccess"

If you installed a native package (.deb, .rpm, or AUR), the rules are installed and activated automatically — no manual steps needed.

If you installed from source (make install), the rules are also installed automatically.

If you built without installing, install the rules manually:

sudo cp data/71-logitune.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules
sudo udevadm trigger

The uaccess tag grants access to the currently logged-in user without requiring root or group membership. After installing the rules, unplug and replug your device (or reboot).

If Logitune starts but shows "No device connected":

1. Check hidraw access: ls -la /dev/hidraw* — your user should have rw access to Logitech devices
2. Check uinput access: ls -la /dev/uinput — needed for keystroke injection
3. Check the device is detected: Run with --debug flag to see device scanning logs

logitune --debug
# or, if running from the build directory:
./build/src/app/logitune --debug

On GNOME Wayland, Logitune uses a Shell extension for focus tracking (per-app profile switching). On first run:

1. The app detects your GNOME Shell version and installs the correct extension variant (v42 for GNOME 42-44, v45 for GNOME 45+) to ~/.local/share/gnome-shell/extensions/logitune-focus@logitune.com/
2. The extension is enabled automatically via D-Bus
3. A Shell restart may be required for the extension to take effect — log out and back in, or press Alt+F2 and type r (X11 only)

You can verify the extension is active:

gnome-extensions list --enabled | grep logitune

All device configuration (buttons, DPI, scroll, gestures, thumb wheel) works without the extension. The extension is only needed for automatic per-app profile switching on focus change.

Logitune uses a lock file at $TMPDIR/logitune.lock to prevent two instances from fighting over the device. If a previous instance crashed without cleanup, delete the lock file manually:

rm /tmp/logitune.lock

The application window is organized into four main areas:

A vertical navigation bar on the left with icons for each page:

The Buttons page shows a rendered image of the device (front view by default, side view available). Interactive hotspots are overlaid at positions defined by the device descriptor — clicking a hotspot opens the action picker for that button.

A horizontal tab bar at the bottom of the window:

• Default tab is always present — this profile is used for applications without a specific binding
• App profiles appear as additional tabs with the application's icon
• The hardware-active profile (the one currently applied to the device) is indicated with a highlight
• The display profile (the one you're currently viewing/editing) may differ from the hardware-active profile
• Click the + button to add a new app profile from the list of installed applications

Profiles are stored per-device under:

~/.config/Logitune/devices/<device-serial>/profiles/

Each profile is a .conf file (QSettings INI format). App bindings are stored in app-bindings.conf in the same directory.

Logitune runs as a tray application — closing the window hides it to the tray rather than quitting. The tray menu shows:

• Battery level — e.g., "Battery: 85%"
• Show — brings the window back
• Quit — exits the application

The application sets quitOnLastWindowClosed(false) so the tray icon keeps the event loop alive.

Debug logging can also be toggled at runtime from the Settings page.

1. Single-instance check — attempts to acquire logitune.lock
2. Log manager init — sets up Qt logging categories, optional file output
3. Crash recovery — checks for previous unclean shutdown, offers to file a bug report
4. AppController init — creates DeviceManager, ProfileEngine, models, wires signals
5. QML engine load — registers model singletons, loads Main.qml
6. Start monitoring — DeviceManager begins udev scanning; desktop integration detects DE (KDE/GNOME/Generic) and starts focus tracking
7. Device connect — on first hidraw match, enumerates HID++ features, reads state, creates command queue
8. Profile load — loads or seeds the default profile, applies settings to hardware
9. Tray icon — system tray icon appears with battery info