Project status: paused. Active development has moved to a new project, SpaceUX, which reworks this functionality from the ground up. This repository stays available and keeps working, but new features and fixes land in SpaceUX instead. Existing reports are noted as design input for the rewrite, so please don't expect fixes here in the meantime.
Userspace control daemon and GUI for 3Dconnexion SpaceMouse devices on Linux. Sits on top of the existing driver stack (Linux evdev + spacenavd + libspnav) and turns 6DOF input into desktop actions: tilt to scroll, push/pull to zoom, twist to switch virtual desktops. Blender and FreeCAD continue to use their native 3D navigation — this project does not interfere with that path.
The current version (0.1.0) is reported by spacemouse-desktop --version, spacemouse-test --version and spacemouse_config.__version__.
-
3Dconnexion SpaceMouse connected via USB
-
A supported distribution. Build, packaging and the install script are continuously verified in CI on:
Distribution Notes Arch Linux (incl. EndeavourOS, Manjaro) libspnavandpyside6fromextra;spacenavdfrom the AUR — needsyayorparu(install yay)Fedora (latest) everything from the official repos (no RPM Fusion needed) Debian 13 (trixie) everything from apt mainDebian 12 (bookworm) / Ubuntu 24.04 LTS / Ubuntu 24.10 works, but PySide6 isn't in apt — the installer falls back to a pip venv automatically. ( python3-pyside6.qtwidgetsfirst lands in Ubuntu 25.10.)openSUSE Tumbleweed / Leap everything from the official repos -
A desktop environment. KDE Plasma (Wayland) is the primary target and the only one where the full feature set works. The control daemon itself is desktop-agnostic — see the table below.
The daemon and GUI both fall back gracefully when a backend isn't available, so nothing crashes on other desktops; the affected features just become no-ops.
| Feature | KDE Plasma | GNOME (X11) | GNOME (Wayland) | XFCE 4.18+ | Sway | Hyprland | COSMIC |
|---|---|---|---|---|---|---|---|
| Scroll, zoom (tilt + push/pull) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Blender / FreeCAD native 3D navigation | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| GUI with system-tray icon | ✓ | ⚠ via AppIndicator extension | ⚠ via AppIndicator extension | ✓ | ✓ via swaybar | ⚠ needs waybar / eww | ✓ via COSMIC panel applet |
| Manual profile switching from the GUI | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Auto profile switch when Blender / FreeCAD is focused | ✓ KWin script | ✓ xprop | ✓ via bundled focus-bridge extension | ✓ xprop | ✓ swaymsg | ✓ socket2 | ✗ no portable API |
| Twist → virtual desktop switch | ✓ KWin D-Bus | ✓ key combo | ✓ key combo | ✓ key combo | ✓ swaymsg | ✓ hyprctl | ✓ key combo |
| Left btn → Overview / Right btn → Show Desktop | ✓ KGlobalAccel | ✓ key combo | ✓ key combo | ✓ key combo | ✓ key combo | ✓ key combo | ✓ key combo |
GNOME-Wayland note: auto profile switching needs a Shell extension because GNOME exposes no portable window-listing protocol and org.gnome.Shell.Eval has been policy-disabled since GNOME 41. The installer ships and enables a small bundled extension (spacemouse-focus@maik-0000ff, source under gnome-extension/) that publishes the focused window's wm_class on the session bus. The GUI subscribes to a D-Bus signal from that extension — push-based, zero compositor load between focus changes — and switches profiles when Blender or FreeCAD gains focus. Log out and back in once after install so GNOME-Wayland loads the new extension — Mutter cannot live-load extensions on Wayland for security reasons. The third-party Window Calls extension is also recognised as a fallback for users who already had it installed (polled every 1.5 s, deliberately slow so Mutter's main loop stays free).
The extension's
shell-versionfield ingnome-extension/spacemouse-focus@maik-0000ff/metadata.jsoncurrently lists GNOME 45–50. When a new major GNOME release ships, append its version number to that array, otherwise GNOME Shell refuses to load the extension.
git clone https://github.com/Maik-0000FF/SpaceMouse_3dconnexion.git
cd SpaceMouse_3dconnexion
./install.shThe installer takes care of everything: installing packages, setting up permissions, compiling the daemon and tools, and starting the background services. You'll be asked for your password when it needs administrator access.
After installation, plug in your SpaceMouse (or unplug and replug it) and it's ready to use.
After installation the daemon runs in the background but is intentionally idle — all axes and buttons start out unassigned. Open SpaceMouse Control from the tray icon and assign actions yourself on the Desktop page:
- Axes can be set to horizontal scroll, vertical scroll, zoom (Ctrl+scroll) or virtual-desktop switching
- Buttons can be set to KDE Overview or Show Desktop
When you switch to Blender or FreeCAD, the desktop daemon steps aside automatically and the app's native 3D navigation takes over — no manual switching needed.
A system tray icon appears in your taskbar. Click it to open SpaceMouse Control — a settings app with three pages:
- Desktop — sensitivity, axis mapping, deadzone, button actions
- FreeCAD — SpaceMouse sensitivity, axis enable/invert, per-axis deadzone, navigation style
- Blender — NDOF sensitivity, deadzone, axis inversion, Lock Horizon toggle
| Desktop | FreeCAD | Blender |
|---|---|---|
 |
 |
 |
A live preview bar at the bottom shows real-time axis movement and button state. While the settings window is focused, desktop actions are automatically disabled so the SpaceMouse doesn't interfere while you configure it.
FreeCAD and Blender connect directly to spacenavd — they don't need the GUI or daemon running. You can close SpaceMouse Control completely and 3D navigation keeps working. Settings are written to each app's config file and persist across restarts.
Blender works out of the box — no extra setup needed.
Important
Open Blender, focus the 3D viewport, and move the puck. The camera should respond immediately. If it doesn't, no setting in this GUI will fix it — the issue is upstream of the configuration layer (Blender's NDOF binding disabled, spacenavd not running, or a hardware problem). Solve that first; only then tweak sensitivity, deadzone, etc.
To configure Blender's SpaceMouse settings from the GUI:
- Open SpaceMouse Control (tray icon) → Blender page
- Adjust sensitivity, deadzone, axis inversion, etc.
- Click Apply
- Click Install Startup Script (first time only)
- Restart Blender — settings are applied automatically on every launch
Tip: If pitch/tilt doesn't work in Blender, make sure Lock Horizon is OFF (Blender enables it by default, which blocks the pitch axis).
Important
Open FreeCAD, load any document, focus the 3D view, and move the puck. The model should rotate or pan. If it doesn't, no setting in this GUI will fix it — your FreeCAD build was likely compiled without spnav, spacenavd is not running, or the device is not detected at all. Fix the underlying problem first; only then adjust sensitivity, axes, deadzone, etc.
To configure SpaceMouse inside FreeCAD, use the FreeCAD page in SpaceMouse Control (tray icon → Settings).
FreeCAD on Linux has had several SpaceMouse-related bugs. Most fixes are now in 1.1.1 and the 1.2 development branch, but jerky navigation (PR #28110) is still missing from the 1.1 series, and the reset-button bug (PR #28956) is open. If you're affected, see freecad/ for a patcher and Arch build that apply the fixes locally — completely separate from the control daemon here.
./uninstall.sh- Check that the device is plugged in:
lsusb | grep -i 3dconnexion - Check that the system daemon is running:
systemctl status spacenavd - Run the built-in diagnostic:
spacemouse-test --check
If spacenavd isn't running:
sudo systemctl enable --now spacenavdThese are upstream FreeCAD issues, unrelated to this project. See freecad/ for the patcher and patched Arch build.
If 3D navigation feels stuttery while only one libspnav client is connected
and goes smooth the moment a second one attaches (e.g. opening
spacemouse-test --live), enable Smooth 3D nav in the sidebar of
SpaceMouse Control. The GUI then keeps a silent second libspnav reader
(spacemouse-test --live, output discarded) attached to spacenavd in the
background for as long as the toggle is on, regardless of which window is
focused. Turning the toggle off stops the reader again.
This mitigates an event-pacing quirk in spacenavd that surfaces on some GNOME-Wayland setups; KDE Plasma is usually unaffected. Off by default.
systemctl --user restart spacemouse-configOn GNOME the tray icon will not appear at all unless the AppIndicator and KStatusNotifierItem Support extension is installed — GNOME has no built-in StatusNotifierWatcher. Install it and log out and back in:
sudo dnf install gnome-shell-extension-appindicator # Fedora
sudo apt install gnome-shell-extension-appindicator3 # Debian/Ubuntu
yay -S gnome-shell-extension-appindicator # Arch (AUR)
sudo zypper install gnome-shell-extension-appindicator # openSUSEManual install: https://extensions.gnome.org/extension/615/appindicator-support/
Until the extension is in place, the GUI auto-opens the settings window on every launch so the app stays reachable. The background daemon (profile switching, scroll/zoom) works regardless of whether the tray is visible.
Open the tray icon settings and check that button actions are set (default: Left = Overview, Right = Show Desktop).
spacemouse-test --check # System checks (USB, spacenavd, uinput)
spacemouse-test --live # Real-time axis and button monitor
spacemouse-test --led # LED toggle test| Device | Status |
|---|---|
| SpaceNavigator (046d:c626) | Tested (fully working, including LED control) |
| SpaceBall 5000 (046d:c621) | Confirmed working |
| SpacePilot (046d:c625) | Confirmed working |
| SpaceMouse Compact | Should work (untested) |
| SpaceMouse Wireless | Should work (untested) |
| SpaceMouse Pro (Wireless) | Should work (untested) |
| SpaceMouse Enterprise | Should work (untested) |
Any 6DOF device supported by spacenavd should work. LED control currently only works for the SpaceNavigator — other models may use different HID report formats.
GPL-3.0-or-later — see LICENSE for the full text. The project links against libdbus-1 (LGPL), libspnav (BSD-3-Clause) and json-c (MIT), all compatible with GPL-3.0 distribution.
SpaceMouse and 3Dconnexion are trademarks of 3Dconnexion GmbH. This project is not affiliated with, endorsed by, or sponsored by 3Dconnexion. The name is used only to identify the hardware this software supports.
The actual SpaceMouse driver stack on Linux is the work of John Tsiombikas and the FreeSpacenav community — without it none of this would exist:
- spacenavd — system daemon that owns the device
- libspnav — client library used by spacenavd-aware apps (Blender, FreeCAD, the diagnostic tool here)
This project is a userspace layer on top of that stack: a control daemon that maps 6DOF input to desktop actions, plus a configuration GUI.
