Linux setup
What a Linux machine needs before Neru runs. X11 needs only the libraries. Wayland also needs two device permissions. Per-desktop notes are in Linux desktops.
Supported desktops
Section titled “Supported desktops”Neru picks a backend once at startup from XDG_CURRENT_DESKTOP,
WAYLAND_DISPLAY and DISPLAY. neru doctor shows it as display_server.
A Wayland session takes wayland-wlroots when XDG_CURRENT_DESKTOP is unset,
names a compositor in the first row, or contains wlroots, as labwc’s
labwc:wlroots does.
| Desktop | Backend | Status |
|---|---|---|
| Sway, Hyprland, niri, River, Wayfire, labwc | wayland-wlroots | Supported |
| Other wlroots compositors (dwl, cage, SwayFX, scroll, …) | wayland-wlroots | If it has the protocols |
| KDE Plasma (Wayland) | wayland-kde | Supported |
| COSMIC (Wayland) | wayland-cosmic | Supported |
| GNOME (Wayland), Budgie | wayland-gnome | Supported with Xwayland and an extension |
| X11: XOrg, i3, GNOME on X11, other window managers | x11 | Supported |
| Cinnamon or Pantheon on Wayland, Weston, Mir shells, any other | wayland-other | Not supported, the daemon refuses to start |
Setup steps
Section titled “Setup steps”-
Install the runtime libraries for your distribution. On X11, you are done.
-
Wayland: join the
inputgroup, so Neru can read the keyboard and run its own[hotkeys]:Terminal window sudo usermod -aG input "$USER" -
Wayland: make
/dev/uinputwritable, so Neru can re-emit keys and scroll:Terminal window echo 'KERNEL=="uinput", GROUP="input", MODE="0660"' | sudo tee /etc/udev/rules.d/99-neru-uinput.rulessudo udevadm control --reload && sudo udevadm trigger -
Log out and back in, or reboot. Group membership does not change until you do. Then check that
idlistsinput, and thatls -l /dev/uinputshows groupinputand modecrw-rw----. If/dev/uinputis missing, runsudo modprobe uinput. -
Run
neru doctor. Every row should be healthy.
The install script offers step 2 for you. If you skip steps 2 and 3, Neru still runs with fewer features. See Running without the permissions.
Runtime libraries
Section titled “Runtime libraries”The binary links these dynamically, and the daemon stops before any Neru code runs if one is missing. The install script lists each missing library first, and on apt, dnf and pacman prints the command that finds its package.
- tesseract reads screen text for
hints.strategy = "vision", and is required whatever the strategy is. - tesseract English language data is a separate package. Without it the
visionstrategy reports thateng.traineddatais missing. SetTESSDATA_PREFIXto use language data from elsewhere, such astessdata_fast. Vim mode also reads the languages in other scripts your locale names, such as Chinese or Russian, when their data is installed. For Chinese that istesseract-langpack-chi_simon Fedora,tesseract-ocr-chi-simon Debian and Ubuntu, ortesseract-data-chi_simon Arch. - pipewire carries screen capture on KDE, but a missing
libpipewire-0.3.sostops the daemon on every desktop. - libei injects input on KDE, COSMIC and GNOME.
- cairo, fontconfig, xkbcommon, the Wayland client library and
libX11,libXtst,libXrandr,libXrender,libXext,libXfixesdraw overlays and talk to the display server. - DejaVu fonts are the overlay fonts when
font_familyis unset, and carry the sticky modifier symbols❖⇧⌥⌃.
copy_text also needs a
clipboard tool. Install wl-copy (package wl-clipboard) on Wayland, or
xclip or xsel on X11. Only that action uses it, so it is optional.
Debian / Ubuntu
Section titled “Debian / Ubuntu”sudo apt-get install -y tesseract-ocr tesseract-ocr-eng fonts-dejavu-coreFind the package for any other missing library with
apt-file search <library> after sudo apt-file update.
Fedora
Section titled “Fedora”The library is tesseract-libs, not tesseract, and it needs
a compatibility link.
sudo dnf install -y \ tesseract-libs tesseract-langpack-eng libei pipewire-libs cairo libxkbcommon \ libX11 libXtst libXrandr libXrender libXext libXfixes \ dejavu-sans-fonts dejavu-serif-fonts dejavu-sans-mono-fontsArch Linux
Section titled “Arch Linux”sudo pacman -S --needed \ cairo wayland libx11 libxtst libxrandr libxrender libxext libxfixes \ libxkbcommon libei fontconfig tesseract tesseract-data-eng libpipewire ttf-dejavuOn KDE, approve screen sharing once, the first time a hint strategy needs a screen capture.
Wayland keyboard capture permissions
Section titled “Wayland keyboard capture permissions”On Wayland, Neru grabs every keyboard with EVIOCGRAB and re-emits keys
through its own uinput keyboard, neru-keyboard-proxy. A mode captures keys
the instant it opens, a hotkey chord never reaches the focused app, and keys
pass straight through between modes. This needs steps 2 and 3.
The input group can read every keyboard on the system, so use a tighter
distro udev or ACL setup if that is too broad.
On success Neru logs Evdev keyboard proxy running at startup and
Using Wayland evdev keyboard capture when a mode opens.
Key remappers (kanata, keyd)
Section titled “Key remappers (kanata, keyd)”A remapper’s auto-detect grabs Neru’s devices too, so exclude them. For kanata:
(defcfg linux-dev-names-exclude ("neru-keyboard-proxy" "neru-pointer-proxy" "neru-keyboard"))Or list your physical keyboards in linux-dev-names-include. For keyd, exclude
-1234:567a, -1234:567b and -1234:5679 under [ids].
Start order depends on the remapper:
- kanata
- Start order does not matter. Neru leaves a keyboard kanata holds to it and captures kanata’s output keyboard.
- If kanata starts later, Neru hands it the keyboards, and takes back any it has not claimed after three seconds.
kanata --nodelaygrabs at once, so start it before Neru.
- keyd
- keyd grabs at once, so start it before Neru.
With either one:
- If a remapper grabs a Neru device anyway, Neru releases every keyboard and logs why. Mode key capture stays off until the daemon restarts.
- Write Neru hotkeys as the keys the remapper emits.
- A remapper output device that also moves the pointer is re-emitted through
neru-pointer-proxy. - Neru takes back the keyboards if the remapper quits.
Other effects of holding the keyboards
Section titled “Other effects of holding the keyboards”- Neru never grabs a keyboard that reports touch or pen position axes, such as a built-in trackpad on the same node. A volume knob does not count.
- Per-device compositor settings, such as a Sway or Hyprland
inputblock or a KDE per-device layout, apply toneru-keyboard-proxywhile the daemon runs. - A laptop touchpad stops pausing while you type. Mark the proxy as built in to restore it.
Wayland scroll injection permissions
Section titled “Wayland scroll injection permissions”On Hyprland, Neru scrolls through a virtual wheel on /dev/uinput, because
Chromium and Electron apps there ignore a scroll sent through the compositor.
Elsewhere it scrolls through the compositor. Most distros make /dev/uinput
root-only. The udev rule in step 3 opens it to the input
group. The same device lets the keyboard proxy re-emit keys and gives
neru key its fast path. Restart the daemon after adding the rule.
Running without the permissions
Section titled “Running without the permissions”Without the input group, Neru’s [hotkeys] do nothing on Wayland. Bind
neru hints and the other modes in your compositor instead. See
Global hotkeys on Wayland.
Without a writable /dev/uinput:
- Modes capture keys through the overlay’s keyboard focus, so a hotkey chord also reaches the focused app.
- On Hyprland, scrolling goes through the compositor instead, which Chromium
and Electron apps there ignore.
neru doctorreports this underscroll. - Modified clicks may degrade, and
general.passthrough_unbounded_keysdoes nothing.
Systemd user service
Section titled “Systemd user service”neru services install writes neru.service to
$XDG_CONFIG_HOME/systemd/user (default ~/.config/systemd/user), enables it
at login, and starts it. ExecStart is the resolved path of the binary you ran,
so reinstall after moving it. Other subcommands are in the
CLI reference.
The unit is anchored on graphical-session.target and needs your session’s
display variables. Desktop environments such as KDE Plasma and wrappers such as
uwsm export them. A bare compositor started from a TTY needs this first in
its config:
exec systemctl --user import-environment \ WAYLAND_DISPLAY DISPLAY SWAYSOCK XDG_CURRENT_DESKTOP XDG_SESSION_TYPEexec dbus-update-activation-environment --systemd \ WAYLAND_DISPLAY DISPLAY SWAYSOCK XDG_CURRENT_DESKTOP XDG_SESSION_TYPEexec systemctl --user start graphical-session.targetHyprland, niri and River use their own socket variable, such as
HYPRLAND_INSTANCE_SIGNATURE or NIRI_SOCKET, in place of SWAYSOCK. If the
service does not start, check systemctl --user status neru.service and
systemctl --user is-active graphical-session.target. If the target stays
inactive, run neru launch from your compositor’s autostart instead.
- oku’s service. With oku 0.18.0 or later,
oku add -g github:y3owk1n/neru --servicewritesoku-neru.serviceon the same target, so the setup above applies to it too. Check it withoku service status neru. Use it orneru services install, not both. - Other init systems. On runit, OpenRC or s6,
neru servicesreports that it is not supported. Runneru launchfrom your session instead. - A unit Neru did not write. Neru manages only units starting with
# Installed by `neru services install`.installanduninstallrefuse any otherneru.service, such as one from Nix or your distribution. To switch, remove yours, for example withsystemctl --user disable --now neru.service, then runneru services install. - Relocated
$XDG_CONFIG_HOME. Set it in your session, not only a shell rc, because the user manager fixes its unit search path at login.neru services installrefuses a directory outside that path.
Known limitations
Section titled “Known limitations”Hint coverage, alerts and the other limits Linux shares with Windows are in Platform support, and the ones only Linux has under Known gaps.
Troubleshooting
Section titled “Troubleshooting”General problems are in Troubleshooting.
“error while loading shared libraries: libtesseract.so.5”
Section titled ““error while loading shared libraries: libtesseract.so.5””Release binaries expect libtesseract.so.5, and Fedora ships
libtesseract.so.5.5. The installer detects this and points here. Add a link,
using the name ls prints:
sudo dnf install -y tesseract-libs tesseract-langpack-engls /usr/lib64/libtesseract.so.5.*sudo ln -s libtesseract.so.5.5 /usr/lib64/libtesseract.so.5Debian, Ubuntu, Arch and builds from source do not need this.
“WAYLAND_DISPLAY is not set”
Section titled ““WAYLAND_DISPLAY is not set””Neru runs under X11 or a TTY, and uses the X11 backend when DISPLAY is set.
When the error comes from the systemd service, see Systemd user service.
“neru does not recognize this Wayland compositor”
Section titled ““neru does not recognize this Wayland compositor””XDG_CURRENT_DESKTOP resolved to wayland-other. Check it against
Supported backends and
Checking compositor protocols.
“failed to connect to Wayland compositor”
Section titled ““failed to connect to Wayland compositor””Check echo $WAYLAND_DISPLAY and that wayland-info (package wayland-utils)
answers.
“Wayland evdev capture unavailable; falling back to overlay keyboard focus”
Section titled ““Wayland evdev capture unavailable; falling back to overlay keyboard focus””Add your user to the input group, log out and back in, and confirm with id.
See Wayland keyboard capture permissions.
“Keyboard capture unavailable: /dev/uinput is not writable”
Section titled ““Keyboard capture unavailable: /dev/uinput is not writable””Modes fall back to the overlay’s keyboard focus. Add the udev rule from step 3 and restart the daemon.
The touchpad stays active while typing
Section titled “The touchpad stays active while typing”libinput pauses a laptop touchpad only for keys from a keyboard it counts as
built in. On Wayland your keys reach libinput through neru-keyboard-proxy,
which is virtual and so counts as external. Mark the proxy as built in with a
libinput quirk:
sudo mkdir -p /etc/libinputsudo tee -a /etc/libinput/local-overrides.quirks <<'EOF'[Neru keyboard proxy]MatchUdevType=keyboardMatchName=neru-keyboard-proxyAttrKeyboardIntegration=internalEOFlibinput reads the file only at startup, so log out and back in. Keys from an external keyboard pass through the same proxy, so they pause the touchpad too.
Sticky modifier indicator shows [][][][]
Section titled “Sticky modifier indicator shows [][][][]”The font lacks the modifier glyphs. Set [sticky_modifiers.ui].font_family to
a family that fc-list : family lists and that renders ❖⇧⌥⌃. An unknown
family falls back to DejaVu Sans.