QKeyMapper: in-memory key mapping for Windows without touching the registry

Mappings live in memory and die with the process

QKeyMapper is an open source key mapping tool for Windows, built with Qt Widgets and the WinAPI in C++, described as compatible with Windows 7, 10 and 11. The architectural claim is simple and unusual: after downloading and extracting the archive you run the executable directly, and the program does not modify the registry and does not require restarting the system, because the mapping conversion is done in memory while the program runs.

That design produces the behaviours the tool is built around. Mapping can be enabled and stopped at any point while the program is running, and the mapping stops automatically when the software exits. There is no persistent state to clean up, no boot-time service to uninstall, and no risk of a mapping surviving a crash and leaving your keyboard unusable.

The scope covers keyboard, mouse, physical gamepad and virtual gamepad, in any combination. The documented cases include mapping a gamepad to keyboard and mouse, using a gamepad stick to move the mouse, mapping keyboard and mouse to a virtual gamepad, and using the mouse to move the sticks of a virtual gamepad.

The device support table is specific about what each side can do. Keyboards and mice support input detection, input mapping, combination keys, and up to ten devices each. A physical gamepad supports detection and combination keys, with up to ten gamepads, but it does not appear as a mapping target. A virtual gamepad supports mapping and combination keys with up to four devices, but not detection, because it is created by the tool rather than plugged in.

The mapping vocabulary runs from macros to key sequences

The documentation explains its own terms in a glossary, and reading it tells you how expressive the tool is.

The mapping start and stop hotkey can be triggered by keyboard, mouse or gamepad, and the default is the left Ctrl key and F6 pressed together. Beyond that, a mapped key is the virtual key that a game or application should receive, and a release mapping is the variant that fires when the original key is lifted, paired with the send timing setting so one physical key can produce different outputs on press and release.

Macros come in two flavours. A macro is added in the macro tab of the macro list window and uses the same authoring format as a mapped key, with each configuration item keeping its own independent macro list, insertable into a mapped key with the form Macro(name). A universal macro is added in the universal macro tab, is shared by every configuration item in the software, and is inserted in the form UniversalMacro(name).

Combinations are written with a plus sign, for example A+B. Key sequences use a different separator and can mix in timing: the example given is A+B with 50 milliseconds, then NONE, then a 200 millisecond wait, then C for 50 milliseconds. Delay sets how long a virtual key stays held, in milliseconds. Auto-repeat sends the mapped key continuously while the original is held, with adjustable interval and separate press and release durations, and the two together form the interval. Lock keeps the mapped key held after one press and releases it on the next press of the original, which pairs with auto-repeat for continuous fire without holding anything.

Per-application mapping sets switch by foreground window

A mapping set is a complete configuration with a name, able to contain several mapping tabs and various settings, and it can be switched automatically by matching the foreground process when auto-match foreground process is enabled.

The mechanism monitors the foreground window, searches the saved mapping sets for the closest match, and switches to that set automatically. The matching data is window information, which the user edits as a process name, window title and window class with a corresponding matching mode, and those three fields are what the foreground monitoring compares against.

The matching modes include a regular expression option for advanced matching of process name, title and class name. The documentation points to a PDF in the software directory describing the regular expression matching rules, and the repository also ships QKeyMapper_Regex.pdf and QKeyMapper_Parameter_Format_Quick_Reference.pdf, so the exact syntax and the parameter format are both documented outside the readme.

There is a fallback behaviour worth knowing. If the global key mapping setting has auto-match enabled and no foreground window matches a saved set within two seconds, the software switches to the global key mapping set, which is the configuration that applies whenever the system is not locked.

Long press, which triggers the mapped key after the original has been held for a set time, and double click, which fires when the original is pressed twice within a set window, complete the trigger vocabulary. A mapping item setting is one row of a mapping tab and holds its own repeat, lock and send timing values.

The interception driver has a documented failure that only a full restart clears

This is the most important part of the documentation for anyone installing the tool, and it is stated as a known issue rather than a possibility.

The multi-device support feature uses the Interception driver. The driver has a known problem: repeatedly unplugging and replugging a keyboard or mouse over USB, disconnecting and reconnecting, or putting Windows to sleep and waking it, causes the system's input device IDs to increase. When the ID count exceeds what the driver supports, ten keyboards and ten mice, the input devices stop working, and only a full restart of the operating system recovers them. A fast restart that preserves the software's running state does not recover them.

The documentation's advice is to read the driver usage notes and the possible side effects before installing the multi-device driver, to install it only when the multi-device feature is genuinely needed, and to back up important data and test in a test environment first. If a keyboard or mouse does become unresponsive, the recovery sequence given is a full system restart, then clicking the multi-device driver uninstall button, then restarting again, after which the system is no longer affected by the driver.

Two more cautions sit alongside it. The Visual C++ Redistributable 64-bit runtime may be needed, with Microsoft's download links given for both 64-bit and 32-bit systems. And the ViGEMBus and vJoy drivers are both virtual gamepad drivers, so installing both at once is discouraged; if virtual gamepad problems appear after a vJoy installation, uninstalling vJoy and checking is the suggested step.

Release archives carry a build date and a manual in HTML

Distribution is a zip archive from the releases page, and the naming convention carries useful information. Packages beginning QKeyMapper_vX.Y.Z_x64 or x86 are the compiled executables, and the Build_YYYYMMDD part is the compilation date, with a newer build date meaning the corresponding release notes describe the added features.

The version choice follows the operating system. Windows 10 and 11 users are recommended to use the Qt6_x64 release package, and the Qt5 package exists only so that Windows 7 machines that cannot run the Qt6 build have something to use. The project description also notes that the tool works on Win7 as well as Win10 and Win11.

Documentation ships with the archive. The release package includes a QKeyMapper user manual in HTML that opens by double clicking and can be read offline in a browser, and the same manual is available online, with a GitHub hosted version and a Cloudflare hosted mirror for networks where GitHub Pages is hard to reach. Both the Chinese and English readmes exist in the repository, and the top level also holds QKeyMapper_README.pdf, the key name reference PDF and the regex PDF.

Release cadence is active rather than occasional. The tags are v1.5.0.20261018 from 2026-10-18, v1.3.8.20260926 and v1.3.8.20260626, and the last push to the master branch was on 2026-10-20, two days after the newest release. The date suffix in the version number means the numbering is tied to the build date rather than to a semantic version scheme.

GPLv3 with an explicit warning against commercial use

The licence is GPLv3, and the project adds an unusually explicit disclaimer on top of it.

The stated terms are that the software is provided as is with no warranty of any kind, that the user bears all risk, and that the developers accept no liability for direct or indirect loss from using it. There are safety reminders: the software involves low-level system operations and drivers, so the user should understand the technical risk, back up important data and verify the behaviour in a test environment, and be careful when granting administrator rights, which some features need. There is a compliance note requiring that the use scenario follow local laws, that the software is for study, research and legitimate personal use, and that it must not be used for anything illegal, malicious, or infringing on others' rights.

The commercial use section is the part that deserves a careful read by anyone considering embedding it. The project states that its purpose is open source sharing and that commercial use is not encouraged, while acknowledging that GPLv3 technically permits it. If commercial use is required, the terms listed are strict: GPLv3 must be kept and the complete source code published, derivative works must also be open sourced under GPLv3, and the software must not be used in any closed source commercial product. The project then advises businesses and commercial users to look for a commercial alternative instead.

That is a project preference rather than a licence change, since GPLv3 itself does not forbid commercial use, but it is a clear signal about the maintainer's intent and about how an enterprise adoption conversation is likely to go.

Editorial conclusion

QKeyMapper suits a Windows player or office user who needs a joystick to drive the mouse, a mouse to drive a virtual gamepad, or a scriptable key sequence, and who wants the change to vanish when the program closes. It does not suit commercial product work, because the project states it is not encouraged for commercial use and that any derivative must stay GPLv3 and open source. Before installing it, read the interception driver note, plan to back up your data, and confirm that a full restart is acceptable, since the documented failure mode leaves the keyboard and mouse unusable until the operating system is fully restarted.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. Releases
5. Zalafina/QKeyMapper on GitHub