Wayland support is here! 🥳 The getting started docs have been updated, but are reprinted here for convenience. Key known issues are listed at the bottom here.
For X11 users: the only update in this version is that those who relied on the --dpi-scale CLI arg or mouse positioning debug options can instead now use the overlay_scaling, mouse_scaling, and mouse_screen_offset_scaling settings found at the bottom of the config editor. These options are likely unneeded on Wayland.
Mint 22 and Ubuntu 24/25 users: If Mouseless is failing to work properly and you're seeing errors like Main_Window call failed with error code: 1. Result: '{"error":"Evaluation failed internally","details":"Unsupported result type"}', the preview.2.1 build at the top of the list will hopefully fix the issue for you (see #485).
Mac and Windows: No builds for this release.
Feedback is always appreciated! 🙏
Getting started
Wayland users: Please see the 'Enabling keyboard/mouse access on Wayland' section below before running Mouseless.
- From https://mouseless.click, download the .AppImage and .sha256sum file for your OS and architecture.
- Verify the download integrity:
sha256sum -c <file>.sha256sum - Make the AppImage executable:
chmod +x <file>.AppImage - Run the application:
./<file>.AppImage - Start a trial or activate with a license key
- Enjoy!
Not working right? See this section for troubleshooting common issues.
Enabling keyboard/mouse access on Wayland
⚠️ Security Note / Context
Wayland's security model prevents apps from having low-level access to keyboard and mouse devices. However, Mouseless requires this low-level access to: utilize global hotkeys; suppress input to apps without stealing focus; and generate mouse events.
This means you must disable Wayland's extra restrictions around keyboard/mouse access for Mouseless to work, i.e. adopt a security model equivalent to X11's. This affects all programs run by your user, not just Mouseless, though there are some alternatives for advanced users mentioned at the bottom.
Disclaimer: The developers of Mouseless are not responsible for any issues that may arise from changing your system configuration or using elevated privileges (sudo). Do so at your own risk.
Method 1 (udev rules)
- Add these rules to allow your user to access input devices:
sudo tee /etc/udev/rules.d/99-mouseless-input.rules <<EOF
# Output: Virtual device creation
KERNEL=="uinput", GROUP="$USER", MODE:="0660"
# Input: Physical device reading
KERNEL=="event*", GROUP="$USER", NAME="input/%k", MODE:="0660"
EOF- Reload the system rules:
sudo udevadm control --reload-rules && sudo udevadm triggerMethod 2 (fallback)
If you still see udev-related errors or 'no keyboards detected' errors when starting Mouseless, this method should work for you.
- Undo rule creation from step 1:
sudo rm /etc/udev/rules.d/99-mouseless-input.rules- Create a systemd temporary file configuration:
# Forces current user/group ownership on input devices
sudo tee /etc/tmpfiles.d/mouseless-input.conf <<EOF
z /dev/uinput 0660 $USER $(id -gn) - -
z /dev/input/event* 0660 $USER $(id -gn) - -
EOF- Apply the permissions:
sudo systemd-tmpfiles --create /etc/tmpfiles.d/mouseless-input.confHotplugging note: The changes made in method 2 persist across reboots, but if you plug in any keyboards after startup, you may need to run the systemd-tmpfiles command (step 3) again to apply permissions to them.
Alternatives (advanced)
Run as root: Instead of changing Wayland's input security, you can simply run Mouseless with sudo. The security implication here is that if a malicious process hijacks the Mouseless process, it will have root access to your system.
Create a dedicated user: You might be able to create a separate system user and assign the needed permissions, then run Mouseless as that user. However, running a GUI app as a different user on Wayland is complex and requires manual configuration to allow the app to connect to your display session. If you figure out a reliable configuration for this, please share! I'd be happy to post community-contributed guides, even if they are specific to certain distros or compositors.
Known issues
The following issues have been reported and are being investigated / worked on soon: