Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Getting started

MacOS

To install (or update):

  • Download the .dmg file from https://mouseless.click
  • Open the .dmg file
  • Drag Mouseless.app into the Applications folder
  • If updating: choose “Replace” instead of “Keep both” when prompted

You can also install in the terminal via Homebrew:

  • brew install --cask mouseless (stable channel)
  • brew install --cask mouseless@preview (prerelease channel)

First time usage:

  • Open Mouseless (e.g. via spotlight search)
  • Read/agree to the terms of service
  • Start trial or activate
  • Give Mouseless the Accessibility permission when prompted
  • Restart the application for permissions to take effect
  • Enjoy!

Windows

To install (or update):

  • Download the latest Windows installer (.exe) or portable (.zip) file from https://mouseless.click
  • Run the installer (or extract the .zip)
  • If installing, choose whether to install for current user (no admin privileges required) or for all users (admin privileges required)
    • On subsequent installations / updates, the installer will use the previously chosen option. To override this, run the installer from the command line with the /ALLUSERS or /CURRENTUSER argument, e.g.: .\mouseless-installer_v0.4.2.exe /CURRENTUSER

First time usage:

  • Open Mouseless, e.g. via the start menu if installed, or if using the portable, by running the mouseless\mouseless.exe file in the extracted folder/location
  • Read/agree to the terms of service
  • Start trial or activate
  • Enjoy!

Linux

Wayland users: Please see the ‘Enabling keyboard/mouse access on Wayland’ section below before running Mouseless. If you’re unsure if you’re on Wayland or X11, run echo $XDG_SESSION_TYPE in a terminal.

  • 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.

Method 1 (udev rules)

  1. 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
  1. Reload the system rules:
sudo udevadm control --reload-rules && sudo udevadm trigger

Method 2 (fallback)

If you still see udev-related errors or ‘no keyboards detected’ errors when starting Mouseless, this method should work for you.

  1. Undo rule creation from step 1:
sudo rm /etc/udev/rules.d/99-mouseless-input.rules
  1. 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
  1. Apply the permissions:
sudo systemd-tmpfiles --create /etc/tmpfiles.d/mouseless-input.conf

Hotplugging 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 can 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.