FAQ & troubleshooting

Short answers to what comes up most. Everything here is on one page — use your browser’s find.

Remapping doesn't work in one specific window

If that window runs as administrator, Windows blocks input from non-elevated programs (UIPI). Run WinRemap elevated too if you really need remapping there. Games with anti-cheat and some virtualization software also ignore injected input.

How do I check what is actually in effect?

Right-click the tray icon and pick Settings. It shows the config WinRemap is resolving against right now — every keymap, its target apps and exclusions, and its rules, each with the comment you wrote beside it in the file. Where the same input is bound in more than one keymap, a column names the others, since only one of them can win.

Press Edit and the same window becomes an editor for the file: rules are checked as you type, saving validates the whole config before it writes a byte, and everything you did not touch — comments, blank lines, ordering, spellings — comes back unchanged. Remapping keeps running the whole time.

My rule doesn't match — how do I debug it?

Right-click the tray icon and pick Show log. It names the config file it loaded, shows the exact application value for each foreground window, and gives one stamped line per key saying what WinRemap did with it (pass-through / remap / macro / prefix) — C-h (BS 0x08) → remapped to Back (BS 0x08). Tick Every event to see the whole stream instead: every press and release, and everything WinRemap sent in reply. Prefer a terminal? Start WinRemap with winremap.exe --debug and the same lines go there instead; without that flag it prints nothing. Debug output never includes typed text and is never written to disk.

One thing to know about --debug: WinRemap opens no console of its own, so your shell does not wait for it. The prompt comes straight back and then repaints itself on top of the log, and the two overwrite each other. Keep the shell out of the way by making it wait:

Start-Process winremap.exe -ArgumentList '--debug' -NoNewWindow -Wait

Stop it with Ctrl+C or from the tray. The log window never has this problem, and it does not need --debug — opening it turns the log on by itself.

Can I use it together with Keyhac / AutoHotkey?

Not recommended for the same keys: stacked low-level keyboard hooks have undefined ordering, so behavior becomes unpredictable. Disable one while testing the other.

How do I turn autostart on or off after installing?

Press Win+R, run shell:startup, and add or remove the WinRemap shortcut there. (Re-running the installer also lets you re-choose the option.)

A macro types too fast for the target app

Set delay_ms = 8 under [macro] (0–15) — some apps sample input asynchronously and drop burst-injected strokes.

Where does WinRemap store things?

Program: %LOCALAPPDATA%\Programs\WinRemap (installer) or wherever you put the portable exe. Config: %APPDATA%\winremap\config.toml. That's all — no services, no drivers, no registry settings.

The Store version lives where Windows puts packaged apps, and gets a private copy of %APPDATA% with it — so a fresh Store install keeps the config under %LOCALAPPDATA%\Packages\SUGANUMADaiki.WinRemap_pktmgf1zdhxe0\LocalCache\Roaming\winremap\. You don't have to remember that: the settings window names the folder it is actually using and opens it in Explorer for you.

How do I verify my download is genuine?

Compare the SHA-256 hash against SHA256SUMS from the release, and check the build-provenance attestation with the GitHub CLI:

(Get-FileHash .\winremap-setup.exe -Algorithm SHA256).Hash.ToLower()
    gh attestation verify .\winremap-setup.exe --repo DaikiSuganuma/winremap

Details in SECURITY.md. The Store version needs none of this — Microsoft signs it, and the Store page names the publisher. Binaries from anywhere other than these two channels are unofficial.

Microsoft Store or GitHub — what's the difference?

Same build, same source, same version. Three practical differences:

  • No SmartScreen warning from the Store — Microsoft signs the package. The GitHub binaries are unsigned, so Windows may warn about a new download.
  • Updates arrive on their own from the Store. With GitHub you download the new version yourself.
  • The config file sits somewhere else. Windows gives packaged apps a private copy of %APPDATA%, so a fresh Store install keeps config.toml under its own package folder rather than %APPDATA%\winremap\. The settings window shows you the folder it is using either way.

Switching is safe: if you already have %APPDATA%\winremap\config.toml from the installer, the Store version keeps using that file, so your rules come with you. Only the GitHub route offers a portable single exe. See the install guide.

I wrote "C-@" and got an error. Why?

Because on your keyboard @ is not a key — it is Shift+2. Write the Shift into the rule:

"C-S-2" = "Esc"

WinRemap tells you this, with the spelling to use, rather than adding the Shift behind your back — otherwise C-@ and C-S-2 would be the same rule on your machine and different rules on someone else's.

On a Japanese keyboard @ is a key of its own, and "C-@" works there. Symbol keys are written the way they are engraved, and which key that is depends on the keyboard — the configuration guide explains it.