How I Fixed My Mechanical Keyboard's Double-Typing with a Python Debounce Filter

My Razer BlackWidow V4's R key started registering twice on every single press. Instead of replacing the switch or the whole board, I wrote a Python script that intercepts the keyboard at the input device level and filters out the ghost keypresses. It runs as a systemd service, starts on boot, and the whole fix took about ten minutes.

The Problem: Key Chatter

If you've used a mechanical keyboard long enough, you've probably run into this: you press a key once, and the computer registers it twice. It's called key chatter, and it happens when the metal contacts inside a mechanical switch bounce as they make contact. Every switch has some bounce. The keyboard's firmware usually handles it with a debounce algorithm. But when a switch starts to wear, the bounce gets worse than the firmware can handle, and you get double-typed characters.

In my case it was the R key. Every "r" came out "rr". Every "return" was "rreturn". Every search query had phantom letters. It was driving me up the wall.

Diagnosing the Issue

Before reaching for a soldering iron, I wanted to confirm this was a hardware chatter issue and not a software misconfiguration. A few quick checks:

Identify the keyboard. On Linux, lsusb lists all connected USB devices:

lsusb | grep -i keyboard
# Bus 001 Device 003: ID 1532:0287 Razer USA, Ltd Razer BlackWidow V4

Check the current repeat rate. The xset command shows how the system handles held keys:

xset q | grep "auto repeat"
# auto repeat delay:  500    repeat rate:  33

The repeat settings looked reasonable. This wasn't a case of the repeat rate being set too aggressively. The issue was genuine switch chatter: the physical contacts inside the R key were bouncing and registering a second keypress within milliseconds of the first.

The Fix: A Software Debounce Filter

The idea is simple: sit between the physical keyboard and the rest of the system, and if the same key fires twice within a very short window (shorter than any human could physically press a key twice), suppress the second event.

Python's evdev library gives us low-level access to Linux input devices. The script grabs exclusive access to the keyboard, creates a virtual copy of it via uinput, and forwards all events through, except rapid duplicate key-down events that arrive faster than the debounce threshold.

#!/usr/bin/env python3
"""Keyboard debounce filter - suppresses key chatter on mechanical keyboards."""

import argparse
import sys
import time

import evdev
from evdev import UInput, ecodes

DEFAULT_DEBOUNCE_MS = 75


def find_keyboard(name_fragment="BlackWidow"):
    for path in evdev.list_devices():
        dev = evdev.InputDevice(path)
        if name_fragment in dev.name:
            caps = dev.capabilities(verbose=False)
            if ecodes.EV_KEY in caps and len(caps[ecodes.EV_KEY]) > 100:
                return dev
    return None


def run(debounce_ms, device_path=None):
    kbd = evdev.InputDevice(device_path) if device_path else find_keyboard()

    if kbd is None:
        print("Keyboard not found.", file=sys.stderr)
        sys.exit(1)

    print(f"Debouncing: {kbd.name} ({kbd.path}), threshold={debounce_ms}ms")

    ui = UInput.from_device(kbd, name=f"{kbd.name} (debounced)")
    kbd.grab()

    last_down = {}
    debounce_s = debounce_ms / 1000.0

    try:
        for event in kbd.read_loop():
            if event.type == ecodes.EV_KEY:
                key_event = evdev.categorize(event)
                if key_event.keystate == evdev.KeyEvent.key_down:
                    now = time.monotonic()
                    if (now - last_down.get(event.code, 0)) < debounce_s:
                        continue  # suppress chatter
                    last_down[event.code] = now

            ui.write_event(event)
            ui.syn()
    finally:
        kbd.ungrab()
        ui.close()


if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("-t", "--threshold", type=int, default=DEFAULT_DEBOUNCE_MS)
    parser.add_argument("-d", "--device", type=str, default=None)
    args = parser.parse_args()
    run(args.threshold, args.device)

How It Works

The script does four things:

1. Finds the keyboard: scans /dev/input/ for the device matching your keyboard's name and picks the one with a full key set
2. Creates a virtual clone: uses Linux's uinput subsystem to create a new virtual keyboard device with the same capabilities as the real one
3. Grabs exclusive access: takes over the physical keyboard so only the script receives its raw events. The rest of the system sees only the filtered virtual keyboard
4. Filters events: for every key-down event, checks if the same key was pressed within the debounce window. If yes, the event is dropped. Everything else passes through untouched

The key insight is the difference between key-down, key-repeat, and key-up events. The script only filters key-down events. Key repeats (when you hold a key) and key-up events pass through without delay, so held keys and releases behave exactly as expected.

Running as a Service

A fix that has to be manually started every time you boot isn't much of a fix. A systemd user service handles that:

[Unit]
Description=Keyboard debounce filter for Razer BlackWidow V4

[Service]
Type=simple
ExecStart=/usr/bin/python3 /home/you/.local/bin/kb-debounce.py --threshold 75
Restart=on-failure
RestartSec=3

[Install]
WantedBy=default.target

Save this as ~/.config/systemd/user/kb-debounce.service, then enable and start it:

systemctl --user daemon-reload
systemctl --user enable kb-debounce.service
systemctl --user start kb-debounce.service

Tuning the Threshold

The threshold value is the key parameter. Too low and chatter still gets through. Too high and you'll notice lag when deliberately double-tapping a key.

• 30ms: aggressive, catches mild chatter but may miss worse switches
• 50-75ms: the sweet spot for most worn switches
• 100ms+: very aggressive, may interfere with fast double-taps in games

I started at 30ms and it wasn't enough. The ghost keypresses were still slipping through. Bumping to 75ms eliminated the problem completely with no perceptible impact on normal typing speed.

To change the threshold, edit the service file and restart:

# Edit the threshold value in the service file
nano ~/.config/systemd/user/kb-debounce.service

# Then reload and restart
systemctl --user daemon-reload
systemctl --user restart kb-debounce.service

This whole fix (diagnosis, script, service, tuning) took about ten minutes and zero dollars. The R key switch on my BlackWidow is definitely wearing out and will eventually need replacing, but until then the software debounce buys me time without any tradeoffs in daily use. If you've got a chattery key, give it a shot before reaching for the soldering iron.

On Windows? Start Here

The script above is Linux-only since it relies on evdev and uinput, which are part of the Linux kernel. If you're dealing with key chatter on Windows, the same concept applies but you'll want one of these tools instead:

• Keyboard Chattering Fix by Elecbits. Free, open-source, runs in the system tray. Set a debounce threshold per key and forget about it. Grab it from GitHub.
• Key Chattering Fix by micclly. Another lightweight open-source option with a simple GUI. Available on GitHub.

If your keyboard has vendor software (Razer Synapse, iCUE, Armoury Crate), check for a debounce setting there first. Some firmware-level debounce adjustments are available through those tools without needing third-party software.

Mark Borden

CTO & Technology Consultant. Building the systems behind 10x faster eLearning at KnowledgeNow.