Release notes from keymapper

5.4.1

2026-03-07T09:01:12Z

Changed

On Windows the mouse is now also only hooked when it has mappings. One can add @grab-device mouse to further hook it unconditionally (#344).
On Windows the devices are unhooked when the active context only contains Any >> Any (#351).
keymapper-launchd also installs the Karabiner-DriverKit-VirtualHIDDevice daemon (#298).
Updated Karabiner-DriverKit-VirtualHIDDevice to version 6.10.0.

Fixed

Fixed expression Any to match all inputs (#351).
Fixed string comparison blocks with empty strings (#334).

5.4.0

2026-03-01T09:38:53Z

Added

Added FreeBSD support (#222).
Allow keymapperctl to press/release non-virtual keys (#348).

Added getenv builtin macro and string comparison blocks (#334). .e.g.:

# activate context when environment variable has some specific value
[getenv["HOSTNAME"] = "LaptopMum"]

Added window title change detection to KWin script (#349).
Improved version mismatch error dialog on Windows.

5.3.2

2026-02-07T10:22:25Z

Changed

Showing path in "Opening configuration file failed" error (#326).

Fixed

Fixed concurrent output on release (#341).
Fixed empty strings in context filters (#329).
Added missing dependency to DEB package.
Bundling documentation (#336).

5.3.1

2025-12-04T19:20:52Z

Fixed

Fixed ContextActive for contexts with device filter (#319).
Fixed keymapperctl --next-key-info (#314).
Fixed disabling notifications (#314).

5.3.0

2025-11-21T19:33:02Z

Added

Added keymapperctl --print "string" (#312).
Allow to pass key Any to keymapperctl --wait-toggled (#312).

Fixed

Retry initializing Winsock when network subsystem is not ready yet (#313).
Fixed path separator in keymapper-launchd (#298).

5.2.0

2025-10-25T08:31:54Z

Added

Added directive @virtual-keys-toggle, which allows to change the behavior of virtual keys in outputs (#309). e.g.

@virtual-keys-toggle true   # true is (still) the default

# toggle Virtual1
F1 >> Virtual1

@virtual-keys-toggle false

# press Virtual1
F1 >> Virtual1

# release Virtual1
F2 >> !Virtual1

# toggle Virtual1
Virtual1{F3} >> !Virtual1
F3 >> Virtual1

Fixed

Improved performance of sending mouse events on Windows (#300).
Fixed output on release with together groups (#306).

5.1.0

2025-10-12T10:15:52Z

Added

Verbose keymapper logging logs virtual key state changes (#297).
Allowing next-key-info to report multiple keys (#212).

Fixed

Fixed obtaining current keyboard layout on X11/XKB (#296).
Ignoring key repeat also when mouse was clicked (#294).
Fixed keymapperctl --toggle when invalid key is passed.

5.0.0

2025-09-02T17:41:21Z

The reason for the major version number increment is mainly because of the changed behavior of ;. Up until 4.9 it was documented to start comments like #. Otherwise all configurations should work like before.

Added

Allow to separate multiple mappings on one line with ;. This is useful for macros which generate multiple mappings. e.g.:
```
swap = $0 >> $1 ; $1 >> $0
swap[Y, Z]
```

Allow to add mappings for inputs which are released. e.g.:

# trigger when A is released
!A >> B

# trigger when B is released while A is held
A{!B} >> C

# trigger when B is released while A is NOT held
!A !B >> C

Toggling virtual keys can also have immediate effects. Using them as modifiers is toggling them twice:

# toggle Virtual1 before and after pressing B
# this effectively maps D to A B C
Virtual1 >> A ^ C
D >> Virtual1{B}

# {} may also be empty. This maps C to A B
Virtual2 >> B
Virtual1 >> A Virtual2{}
C >> Virtual1{}

Automatically replace Virtual with an unused virtual key. e.g.:

# assign different virtual keys to VimMode and CapsWord
VimMode = Virtual
CapsWord = Virtual

Added keymapperctl operation --notify for showing notifications (#282). e.g.:
```
notify = $(keymapperctl --notify "$0")
F1 >> notify["Test"]
```
Added toggle-active directive, which allows to set a sequence that de-/activates keymapper (#283). e.g.:
```
@toggle-active ScrollLock
```
Added include-optional directive, which includes a file but does not fail when file does not exist.

Fixed

Fixed suppressed modifiers getting reapplied (#291).
Fixed loading config from "%HOME%\.config\keymapper" on Windows (#292).
Properly releasing keys when UAC prompt appeared on Windows.

4.12.3

2025-07-13T06:32:17Z

Fixed

Fixed problem with virtual keys (introduced in 4.12.1 for #275).
Fixed checking for a specific number of mouse wheel events (#280).

4.12.2

2025-06-29T10:34:34Z

Added

Showing a hint in "Next Key Info" that Gnome/KDE script is not enabled.

Changed

Handling only lowres wheel events by default on Linux (#268).

Fixed

Not blocking when opening configuration from tray on Linux (#220).
Fixed focus update when xwayland app is minimized to tray (#220).
Fixed device context fallthrough (#277).
Optimized SVG icon.