Skip to main content

Mechanical-Keyboards

QMK & VIA Firmware Guide: Program Your Keyboard

9 min read Updated Feb 1, 2026

A laptop running a keyboard layout editor (VIA/QMK) beside a compact keyboard and USB cable, with a small layers cheat sheet on the desk, soft neutral lighting, realistic photography

QMK & VIA Firmware Guide

Programming your keyboard unlocks its full potential. The goal isn’t to turn your keyboard into a science fair project—it’s to make the board fit your hands and your habits: put Backspace where you want it, make a compact layout behave like a full-size board, and turn repetitive actions into one-keystroke moves.

Two tools dominate modern customs: VIA (the easiest way to remap keys instantly) and QMK (the deep, programmable foundation underneath). You can start with VIA in minutes, and “graduate” into QMK only when you want features that a GUI can’t expose.

What Is Keyboard Firmware?

Firmware Explained

Firmware is the software embedded in the keyboard that translates a physical keypress into the signal your computer receives. It’s why the same physical key can be “A” today, “Escape” tomorrow, and “Mute” on a different layer—without installing drivers or changing anything on your computer.

Firmware controls key mapping, layers (multiple layouts on one keyboard), macros (shortcuts and sequences), lighting, and “behavior features” like tap‑hold actions, key combos, or mouse keys.

QMK Firmware

What Is QMK?

QMK (Quantum Mechanical Keyboard) is open-source keyboard firmware that offers the deepest customization most people will ever need. It’s the “write your own behavior” option: you define what keys do, how layers behave, and how special interactions work.

In QMK you can build custom keymaps, use many layers (often far more than you’ll realistically use), create macros and shortcuts, and enable advanced behaviors like tap‑dance (tap vs hold), combos (multiple keys trigger an action), mouse keys, and RGB control. Some boards also support audio features.

QMK is common in custom keyboards and DIY kits, and it’s also supported by many enthusiast-friendly prebuilts (for example, some Keychron Q-series boards).

The trade-off is workflow: you edit a keymap, compile firmware, and flash it to the keyboard.

Difficulty is moderate. You don’t need to be a professional developer, but you do need comfort following instructions and troubleshooting basic tooling.

QMK Pros and Cons

QMK’s upside is power: it’s open-source, widely supported, constantly improved, and can express almost any behavior you can describe. The downside is friction: you compile, you flash, and you’ll eventually touch code.

VIA

What Is VIA?

VIA is a graphical interface that talks to VIA-enabled QMK firmware. It’s the “move keys around and it just works” experience: no compiling, no flashing (once the board is VIA-enabled), and instant feedback.

With VIA you get real-time remapping, visual layer editing, basic macro creation, and lighting control. The defining feature is immediacy: changes apply instantly.

Compatibility depends on whether your keyboard is running VIA-enabled firmware. Many enthusiast boards support it, but it’s not universal.

The workflow is simple: open VIA (web or desktop), plug in the keyboard, and drag keys to remap.

Difficulty is low; it’s designed for beginners.

VIA Pros and Cons

VIA’s upside is speed and simplicity: it’s beginner-friendly, changes are instant, and settings persist on the keyboard. The downside is that it can’t expose every advanced QMK behavior, and you need VIA support on the board.

QMK vs. VIA Comparison

Here’s the practical difference. VIA optimizes for speed: you make a change and feel it immediately. QMK optimizes for control: you can define deeper behaviors, but you pay with a compile/flash loop.

For most people, VIA is the right starting point. Move keys, build a couple layers, and get your board “comfortable.” Reach for full QMK when you want things like complex tap‑hold behaviors, combos, custom macros, or anything that requires logic beyond what a GUI can express.

Verdict:

  • Use VIA if you want easy, real-time remapping
  • Use full QMK if you need advanced features

Getting Started with VIA

Step 1: Check VIA Compatibility

Does your keyboard support VIA?

  • Check manufacturer website
  • Look for “VIA support” in specs
  • Search keyboard model + “VIA” online

Popular VIA Keyboards:

  • Keychron Q-series
  • GMMK Pro
  • Mode Sonnet/Envoy
  • KBDfans keyboards (many)
  • Most custom keyboards

Step 2: Download VIA

Options:

  1. Web version: https://usevia.app (no installation)
  2. Desktop app: Download from https://github.com/the-via/releases

Recommended: Web version is easiest (works in browser).

Step 3: Connect Keyboard

  1. Plug in keyboard via USB
  2. Open VIA (web or app)
  3. VIA should auto-detect keyboard
  4. Keyboard layout appears on screen

Troubleshooting:

  • If not detected, check if keyboard has VIA firmware
  • Try different USB cable/port
  • Restart VIA application

Step 4: Remap Keys

How to Remap:

  1. Click key you want to change (on virtual keyboard)
  2. Click new key from bottom panel
  3. Key instantly remaps!

Example:

  • Click Caps Lock key
  • Select “Backspace” from panel
  • Caps Lock is now Backspace

Step 5: Create Layers

What Are Layers? Multiple keyboard layouts accessed with a layer key.

Why Use Layers?

  • Access more functions on compact keyboards
  • Create specialized layouts (gaming, coding, media)
  • Eliminate need for function row on 60% keyboards

How to Add Layer:

  1. Click layer number at top (Layer 0, 1, 2, 3)
  2. Remap keys for that layer
  3. Assign layer toggle key (MO(1), TG(1), etc.)

Example:

  • Layer 0: Default typing layout
  • Layer 1: Media controls, arrow keys, function keys
  • Access Layer 1 by holding Fn key

Step 6: Create Macros

What Are Macros? Automated key sequences triggered by one key.

Uses:

  • Common phrases (“Best regards,”)
  • Code snippets
  • Application shortcuts
  • Passwords (use cautiously!)

How to Create Macro in VIA:

  1. Go to “Macros” tab
  2. Click empty macro slot
  3. Type text or key sequence
  4. Assign macro to key on keyboard

Example Macro:

  • Macro: “Best regards, [Your Name]”
  • Assign to unused key
  • One keypress types entire phrase

Getting Started with QMK (Advanced)

Step 1: Set Up QMK Environment

Prerequisites:

  • Basic command line knowledge
  • Text editor (VS Code recommended)
  • Git installed

Setup:

  1. Install QMK Toolbox (for flashing)
  2. Clone QMK firmware repo: git clone https://github.com/qmk/qmk_firmware.git
  3. Install QMK CLI: python3 -m pip install qmk
  4. Set up environment: qmk setup

Alternative (Easier): Use QMK Configurator (web-based): https://config.qmk.fm

Step 2: Find Your Keyboard

In QMK Firmware:

  1. Navigate to keyboards/ folder
  2. Find your keyboard brand/model
  3. Locate keymaps/ folder

Example: For Keychron Q1, go to: keyboards/keychron/q1/keymaps/

Step 3: Edit Keymap

Keymap File: Usually keymap.c in your keyboard’s keymap folder.

Basic Keymap Structure:

const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
    [0] = LAYOUT(
        KC_ESC,  KC_1,    KC_2,    KC_3,    // Row 1
        KC_TAB,  KC_Q,    KC_W,    KC_E,    // Row 2
        // ...
    ),
};

Key Codes:

  • KC_A to KC_Z: Letters
  • KC_1 to KC_0: Numbers
  • KC_ENT: Enter
  • KC_BSPC: Backspace
  • KC_SPC: Space

Full list: https://docs.qmk.fm/#/keycodes

Step 4: Add Layers

Layer Syntax:

const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
    [0] = LAYOUT( /* Base layer */
        KC_ESC,  KC_1,    KC_2,    MO(1),   // Hold 4th key for layer 1
    ),
    [1] = LAYOUT( /* Layer 1 - Media */
        KC_MUTE, KC_VOLD, KC_VOLU, _______,  // Media controls
    ),
};

Layer Keys:

  • MO(1): Momentary layer (hold to activate)
  • TG(1): Toggle layer (tap to switch)
  • LT(1, KC_SPC): Tap for space, hold for layer 1

Step 5: Compile Firmware

Command:

qmk compile -kb <keyboard> -km <keymap>

Example:

qmk compile -kb keychron/q1 -km default

Output: Compiled .hex or .bin file in qmk_firmware/ root.

Step 6: Flash Keyboard

Using QMK Toolbox:

  1. Open QMK Toolbox
  2. Load compiled .hex or .bin file
  3. Put keyboard in bootloader mode:
    • Press reset button on PCB, OR
    • Hold Esc while plugging in, OR
    • Use assigned reset key
  4. Click “Flash” in QMK Toolbox
  5. Wait for completion
  6. Keyboard reboots with new firmware

Common QMK Features

Tap Dance

What It Is: Different actions for tap vs. hold vs. double-tap.

Example:

  • Tap: E
  • Hold: Ctrl
  • Double-tap: Esc

Use Case: Maximize functionality on compact keyboards.

Mouse Keys

What It Is: Control mouse cursor with keyboard keys.

Use Case: Navigate without mouse (keyboard-only workflow).

Keys:

  • KC_MS_U: Mouse up
  • KC_MS_D: Mouse down
  • KC_BTN1: Left click
  • KC_BTN2: Right click

Combos

What It Is: Press multiple keys simultaneously for action.

Example:

  • Press J + K together = Esc

Use Case: Home row shortcuts, reducing pinky strain.

Auto Shift

What It Is: Hold key longer to get shifted version (no Shift key needed).

Example:

  • Tap A = a
  • Hold A (200ms) = A

Use Case: Reduce Shift key usage.

Layer Examples

Example 1: 60% Keyboard with Function Row Layer

Layer 0 (Base):

  • Standard QWERTY layout
  • No F-row or arrow keys

Layer 1 (Fn Layer):

  • Number row becomes F1-F12
  • WASD becomes arrow keys
  • Media controls on right side

Access: Hold Fn key to activate Layer 1.

Example 2: Gaming Layer

Layer 0 (Typing):

  • Standard layout

Layer 1 (Gaming):

  • Caps Lock → Crouch
  • Tab → Inventory
  • Q/E → Lean left/right
  • Media controls disabled (prevent accidental press)

Access: Toggle Layer 1 with Fn+G.

Example 3: Numpad Layer for 60%

Layer 0 (Base):

  • Standard layout, no numpad

Layer 1 (Numpad):

  • Right side of keyboard becomes numpad
  • 7 8 9 → Numpad 7 8 9
  • U I O → Numpad 4 5 6
  • J K L → Numpad 1 2 3

Access: Hold Fn to activate numpad layer.

Macro Examples

Example 1: Email Signature

Macro:

Best regards,
John Doe
john.doe@example.com

Use: One keypress types full signature.

Example 2: Zoom Controls

Macros:

  • Macro 1: Ctrl+Alt+A (mute/unmute audio)
  • Macro 2: Ctrl+Alt+V (start/stop video)
  • Macro 3: Ctrl+Alt+H (hand raise)

Use: Quick Zoom controls without remembering shortcuts.

Example 3: Code Snippets

Macro:

for (int i = 0; i < ; i++) {

}

Use: One keypress inserts common code structure.

Troubleshooting

Keyboard Not Detected in VIA

Solutions:

  • Check VIA compatibility
  • Update VIA firmware
  • Try different USB port/cable
  • Restart VIA application

QMK Compile Errors

Solutions:

  • Check syntax errors in keymap.c
  • Update QMK firmware: qmk update
  • Verify keyboard path is correct
  • Check QMK documentation for key codes

Flashing Fails

Solutions:

  • Ensure keyboard is in bootloader mode
  • Try different USB port (preferably USB 2.0)
  • Check .hex/.bin file path is correct
  • Verify QMK Toolbox has correct MCU selected

Keys Not Working After Flash

Solutions:

  • Reflash with known-good firmware
  • Check keymap for errors
  • Verify matrix pin configuration
  • Test with default keymap first

For 60% Keyboards

Layer 0: Standard typing Layer 1: Arrow keys (WASD), F-row (number row), media Layer 2: Numpad (right side) Layer 3: RGB control, reset, system functions

For 65% Keyboards

Layer 0: Standard typing (has arrows already) Layer 1: F-row, media controls Layer 2: Numpad, macros Layer 3: System functions

For 75% Keyboards

Layer 0: Standard typing (has F-row and arrows) Layer 1: Media controls, macros Layer 2: Advanced functions, RGB

Resources

Official Documentation

Community Resources

Takeaway

VIA is best for:

  • Beginners
  • Real-time remapping
  • Simple macros and layers

QMK is best for:

  • Advanced users
  • Complex features (tap dance, combos)
  • Ultimate customization

Start with VIA: Easy to learn, instant results.

Graduate to QMK: Once you need advanced features.

Programming transforms keyboards: Unlock efficiency, personalization, and workflow optimization.

Next Steps