Ghub4Linux

Logitech Ghub on Linux with DPI settings, RGB lighting and profile management.

A GTK4/libadwaita application that lets you configure your Logitech mouse on Linux (DPI settings, RGB lighting effects, and saving/switching device profiles).

Not implemented yet

Macros and per-application profiles can be stored in the GUI, but they are not executed or applied:

• macro bindings are saved with their action lists, but there is no macro playback (that needs evdev/uinput)
• application profiles are saved per executable, but there is no window watcher that switches the active profile when an application gains focus

---

Installation

Quick install (all distributions)

The install.sh script installs the Python package and registers the application so it appears in your desktop environment's application menu (GNOME, KDE, XFCE, …).

git clone https://github.com/MrSchnirschuh/Ghub4Linux.git
cd Ghub4Linux

Install system dependencies first (see the distribution-specific sections below), then run one of the following:

bash install.sh          # installs for the current user (no root needed)

bash install.sh --system # installs system-wide (requires sudo)

After that you can start Ghub4Linux from your application launcher or from a terminal:

ghub4linux

Note: If the ghub4linux command is not found after installation, add ~/.local/bin to your PATH by adding this line to your shell profile (~/.bashrc, ~/.zshrc, ~/.config/fish/config.fish, …):

export PATH="$HOME/.local/bin:$PATH"

---

Step-by-step: Arch Linux / CachyOS

1. Install system dependencies

sudo pacman -S python python-gobject gtk4 libadwaita hidapi

2. Clone the repository

git clone https://github.com/MrSchnirschuh/Ghub4Linux.git
cd Ghub4Linux

3. Install (package + desktop entry + icon)

bash install.sh

install.sh automatically creates a virtual environment at ~/.local/share/ghub4linux/venv and installs the package there, so no manual python -m venv step is needed.

---

Step-by-step: Ubuntu / Debian

1. Install system dependencies

sudo apt install \
    python3 python3-venv python3-gi python3-gi-cairo \
    gir1.2-gtk-4.0 gir1.2-adw-1 \
    libhidapi-hidraw0

2. Clone the repository

git clone https://github.com/MrSchnirschuh/Ghub4Linux.git
cd Ghub4Linux

3. Install (package + desktop entry + icon)

bash install.sh

install.sh automatically creates a virtual environment at ~/.local/share/ghub4linux/venv and installs the package there, so no manual python3 -m venv step is needed.

---

Autostart

Preferences → Auto-start writes or removes ~/.config/autostart/com.github.mrschnirschuh.ghub4linux.desktop (honours $XDG_CONFIG_HOME). Nothing else reads that file — it is exactly the switch's effect, and the config value is only saved when the file on disk matches the request. There is no tray icon, so the only other preference that used to exist ("start minimized", "minimize to tray") is gone rather than pretending.

udev rules (HID access without root)

By default, HID devices are only accessible by root. Create the following udev rule to allow your user to access Logitech devices:

sudo tee /etc/udev/rules.d/99-logitech-hid.rules <<'EOF'
# Logitech HID devices
SUBSYSTEM=="hidraw", ATTRS{idVendor}=="046d", MODE="0660", GROUP="input", TAG+="uaccess"
EOF

sudo udevadm control --reload-rules
sudo udevadm trigger

TAG+="uaccess" grants the user of the active seat session access via ACL. Add your user to the input group as well — the headless daemon runs as a user service and without an active session gets no ACL:

sudo usermod -aG input $USER
# Log out and back in for the group change to take effect

---

Project structure

Ghub4Linux/
├── install.sh              # One-command install + desktop registration
├── pyproject.toml          # Project definition & dependencies
├── README.md
├── data/
│   ├── com.github.mrschnirschuh.ghub4linux.desktop  # Desktop entry
│   └── icons/hicolor/scalable/apps/
│       └── com.github.mrschnirschuh.ghub4linux.svg  # Application icon
├── packaging/
│   ├── arch/PKGBUILD
│   └── flatpak/com.github.mrschnirschuh.ghub4linux.yml
├── src/
│   └── ghub4linux/
│       ├── __init__.py     # Package metadata
│       ├── __main__.py     # GUI entry point
│       ├── cli.py          # Headless CLI
│       ├── main.py         # GTK4/Adwaita application
│       ├── core/           # config, device, HID
│       └── devices/        # Per-device drivers (G502, G502X Plus, …)
└── tests/                  # pytest suite

Headless CLI

The same package provides ghub4linux-cli for scripting and headless use:

ghub4linux-cli list
ghub4linux-cli info 046d:407f:abc123
ghub4linux-cli --json info 046d:407f:abc123        # i3blocks/polybar friendly
ghub4linux-cli dpi 046d:407f:abc123 --dpi 1600
ghub4linux-cli profile list 046d:407f:abc123

Headless-Daemon (ohne GUI)

ghub4linux-cli daemon läuft ohne GUI im Hintergrund. Es sucht in jedem Durchlauf (--interval, Standard 60 Sekunden) nach Geräten und liest bei verbundenen Geräten den Akkustand; unter 20 % wird eine Warnung ins Log geschrieben. Beenden mit SIGTERM/SIGINT (Ctrl+C bzw. systemctl --user stop).

Als systemd-User-Unit einrichten (startet mit der Login-Session, kein root, keine systemweite Installation):

ghub4linux-cli install-daemon
systemctl --user daemon-reload && systemctl --user enable --now ghub4linux.service

Die Unit landet unter ~/.config/systemd/user/ghub4linux.service, ihr ExecStart zeigt auf den absoluten Pfad der CLI. Logs:

journalctl --user -u ghub4linux.service -f

HID-Zugriff braucht die udev-Regeln und die input-Gruppe aus dem Abschnitt udev rules.

Development

Run tests and lint locally with the provided Makefile:

make test   # pytest
make lint   # ruff check + format check
make format # auto-format with ruff

These targets need the dev extras (python3 -m pip install -e '.[dev]'); the Makefile uses python3 by default and PYTHON=/path/to/python3 make test picks another interpreter.

License

GPL-3.0-or-later