NumLockW

A Wayland Clone of numlockx

Debug

Enable debug mode via environment variable to see detailed logs for troubleshooting:

NUMLOCKW_DEBUG=1 numlockw on

Install

To install numlockw, use the following commands:

sudo usermod -a -G plugdev $USER  # For Arch users: Refer to https://wiki.archlinux.org/title/Udev#Allowing_regular_users_to_use_devices
pipx install numlockw # or pipx install git+https://github.com/xz-dev/numlockw.git

You can then check the available commands with:

numlockw --help

And simply run:

numlockw on

Example output:

usage: numlockw [-h] [--device-name DEVICE_NAME] [--no-fake-uinput]
                [--pre-hook PRE_HOOK] [--force-led]
                {on,off,toggle,status,list-devices} ...

numlockw is a program to control the NumLock key, designed for use with
Wayland and tty environments.

options:
  -h, --help            show this help message and exit
  --device-name, --dev DEVICE_NAME
                        The name of the input device or "*" for each one. If
                        not provided, will fake keyboard to enable NumLock,
                        and enable LDE_NUML on all devices that support it.
  --no-fake-uinput      Do not fake uinput device, use real devices
  --pre-hook PRE_HOOK   A command to run when NumLock is toggled. The command
                        will be run with the status of uinput device name
                        ${{udevice}}.
  --force-led           Force setting LED_NUML on all devices that support it,
                        not dependent system to set it.

actions:
  valid actions

  {on,off,toggle,status,list-devices}
                        action to perform on NumLock
    on                  Turn NumLock on
    off                 Turn NumLock off
    toggle              Toggle NumLock
    status              Display NumLock status
    list-devices        List devices that support NumLock

Use Notes

1. Sometimes, you might need some operation before "Click" NumLock. You can try --pre-hook

numlockw --pre-hook 'echo ${{udevice}}' on  # Print uinput (Fake keyboard) device name

2. Choice exist(real) keyboard to "Click" NumLock:

numlockw --device-name 'AT Translated Set 2 keyboard' on

3. If you want to Force enable/disable LED with switch NumLock by some reason:

numlockw list-devices
numlockw --device-name 'AT Translated Set 2 keyboard' --force-led on  # Only for 'AT Translated Set 2 keyboard'

Background

Why create it?

• River: Does not enable Num Lock at boot.
• numlockx is not available for Wayland.

Why not use the wlroots protocol?

• The functionality of the protocol depends on its implementation by the compositor.

Why should it work?

Refer to the Activating NumLock on Bootup - ArchWiki for background information.

Issues

1. Sync status on LED and actual state:

   • The method described here seems problematic, but no better solution was found.

2. Is it working? (welcome add more):

   • I have tested NumLockW on TTY, KDE (Wayland) and Hyprland, and everything is working fine.
   • Qtile: Work. Confirmed by user (issue #3).
   • However, there are some issues that require attention from the compositor developers:
     • River: Work. Recommend select an exist devices. Issue of River: Add all your keyboards to a keyboard group in ~/.config/river/init, like:

       > riverctl list-inputs
       
        keyboard-13364-832-Keychron_Keychron_V4
            configured: false
       
        keyboard-1-1-AT_Translated_Set_2_keyboard
            configured: false
       
        keyboard-0-0-wlr_virtual_keyboard_v1
            configured: false
       > riverctl keyboard-group-create default
       > riverctl keyboard-group-add default 'keyboard-1-1-AT_Translated_Set_2_keyboard'
       > riverctl keyboard-group-add default 'keyboard-13364-832-Keychron_Keychron_V4'
       

       Then:

       numlockw --device-name 'AT Translated Set 2 keyboard' on
       

     • GNOME: Work. But you must choice an exist keyboard, like: numlockw --device-name 'AT Translated Set 2 keyboard' on

3. Set udev rules for Debian (issues #2):

   • Add file /etc/udev/rules.d/10-uinput.rules

     KERNEL=="uinput", SUBSYSTEM=="misc", OPTIONS+="static_node=uinput", TAG+="uaccess", GROUP="input", MODE="0660"
     

   • Then reboot

Contributing

We warmly welcome contributions from the community. If you find any bugs or have suggestions for improvements, please feel free to open an issue.

You're also encouraged to submit pull requests to help make this project better. If you find this project useful, please consider giving it a ⭐ to show your support!

Thank you for your interest and contributions! ❤️