QMK OS detection

QMK, keyboards

I recently learned that QMK can automagically detect what OS they are connected to, which is pretty cool!

I didn’t find the official documentation very helpful so I thought I would document my setup here in case anyone else needs it.

It’s fairly straight forward. First, enable the feature in your keyboards file:


Then, add the following section to your keymap.c:

uint32_t custom_os_settings(uint32_t trigger_time, void *cb_arg) {
  os_variant_t host = detected_host_os();
  uint16_t retry_ms = 500;

  if (host == OS_MACOS || host == OS_IOS) {
    keymap_config.swap_lalt_lgui = true;
    keymap_config.swap_ralt_rgui = true;
    retry_ms = 0;

  return retry_ms;

void keyboard_post_init_user(void) {
  defer_exec(100, custom_os_settings, NULL);

In my case, I want my keyboard to switch ALT & GUI when connected to a macOS/iOS device. Above does that but lets it take some time (~500 ms) if needed. I’m using macros to enable this, due to reasons.

You can also match on OS_LINUX and OS_WINDOWS (or OS_UNSURE) but I haven’t found any use for these yet. I’ve toyed with the idea of using different backlighting colors for different OS, but I couldn’t make it work on my first try so I haven’t bothered yet. :-)