[Windows] win32_event_filter returning False prevents on_press/on_release callbacks from receiving the event

[redstoneleo]

Description

When using keyboard.Listener on Windows, if you provide a win32_event_filter and return False to suppress a specific key from reaching the OS, that key is ALSO incorrectly hidden from the Listener's own

on_press and

on_release callbacks.

This makes it impossible to implement "selective key suppression" (e.g., intercepting a specific physical key to use as a macro trigger while allowing all normal typing to pass through, and then handling the macro logically inside

on_press).

To work around this currently, developers are forced to fire their custom logic directly inside the win32_event_filter thread, which is dangerous as it risks stalling the global Windows keyboard hook.

Minimal Reproducible Example

from pynput import keyboard

# For this example, we want to suppress the "Right Arrow" key from the OS,
# but still want to detect it in Python to trigger some application logic.
TARGET_VK = 0x27  # VK_RIGHT

def win32_event_filter(msg, data):
    if data.vkCode == TARGET_VK:
        # Return False to suppress this key from being sent to the OS/other apps (Works)
        return False
    return True

def on_press(key):
    # BUG: If the key was suppressed in win32_event_filter, 
    # this callback is NEVER fired for it!
    print(f"Python on_press received: {key}")

def on_release(key):
    # This also never fires for the suppressed key.
    if key == keyboard.Key.esc:
        return False

print("Press the Right Arrow key. Notice how it is suppressed from the OS, but also disappears from on_press.")
with keyboard.Listener(
        on_press=on_press,
        on_release=on_release,
        win32_event_filter=win32_event_filter) as listener:
    listener.join()

Expected behavior

When win32_event_filter returns False, it should suppress the event from propagating to the operating system/other applications (i.e., return 1 from the Windows Hook), BUT it should still dispatch the event to the

on_press and

on_release callbacks so the Python application can handle the key it intentionally intercepted.

Actual behavior

The key is suppressed from the OS successfully, but

on_press and

on_release are never triggered for that key.

Environment

• OS: Windows 10/11
• pynput version: (You can fill in your actual version here, usually 1.7.6 or latest)

[phpjunkie420]

The problem isn't with Windows; it's a structural limitation inside pynput. Currently, when pynput tells Windows to drop the key, it also halts its own internal event pipeline. Because it aborts the entire process, your on_press and on_release callbacks are skipped.

To resolve this, pynput's internal logic would need to decouple the OS-level response from the Python-level dispatching. It needs the ability to tell Windows, "drop this key," while still internally forwarding that intercepted key to your on_press callbacks so your Python script can react to it.



I asked Gemini about this and this is Gemini's response. The code in Gemini's response has been rewritten, documented, and tested.

Update 05/27/2026: I 've updated the code in the Gemini response so the script can cleanly close without ghosting API threads.

---

You cannot intercept keys before the OS receives them using the user-mode Windows API. When a key is pressed, it generates a hardware interrupt that is immediately picked up by the OS kernel and the keyboard class driver.

However, you can intercept and block keystrokes after the kernel processes them but before they reach any user-mode application or the Windows shell.

This is accomplished using a low-level keyboard hook: SetWindowsHookEx with the WH_KEYBOARD_LL (hook ID 13) parameter.

How WH_KEYBOARD_LL Works

When you install a low-level keyboard hook, Windows places your callback function at the beginning of the hook chain for keyboard events. Every time a key state changes, the OS context-switches to your thread to execute your callback.

To block the key, your callback function simply returns a non-zero value (typically 1). This prevents the OS from passing the message down the hook chain or placing it in the target application's message queue. To allow the key through, you return the result of CallNextHookEx.

Python ctypes Implementation

Here is how you can implement this low-level interception using Python and ctypes, which allows direct interaction with the underlying Windows C data types and memory.

This script intercepts all keyboard input and selectively blocks the "A" key (vkCode == 0x41), while letting everything else pass.

import ctypes
import subprocess
import sys
from collections.abc import Callable
from enum import IntEnum
from ctypes import wintypes

subprocess.call('cls', shell = True)


# region Win32 API
# https://learn.microsoft.com/en-us/windows/win32/api/winuser/ns-winuser-kbdllhookstruct
# typedef struct tagKBDLLHOOKSTRUCT {
#   DWORD     vkCode;
#   DWORD     scanCode;
#   DWORD     flags;
#   DWORD     time;
#   ULONG_PTR dwExtraInfo;
# } KBDLLHOOKSTRUCT, *LPKBDLLHOOKSTRUCT, *PKBDLLHOOKSTRUCT;
class KBDLLHOOKSTRUCT(ctypes.Structure):
    vkCode: int
    scanCode: int
    flags: int
    time: int
    dwExtraInfo: int

    _fields_ = [
        ("vkCode", wintypes.DWORD),
        ("scanCode", wintypes.DWORD),
        ("flags", wintypes.DWORD),
        ("time", wintypes.DWORD),
        ("dwExtraInfo", ctypes.POINTER(wintypes.ULONG)),
    ]


# https://learn.microsoft.com/en-us/windows/win32/api/winuser/nc-winuser-hookproc
# HOOKPROC Hookproc;
#
# LRESULT Hookproc(
#        int code,
#   [in] WPARAM wParam,
#   [in] LPARAM lParam
# )
# {...}
_HOOKPROC = ctypes.WINFUNCTYPE(
    ctypes.c_ssize_t,
    ctypes.c_int,
    wintypes.WPARAM,
    wintypes.LPARAM
)


def HOOKPROC(func: Callable[[int, int, int], int]) -> _HOOKPROC:
    return _HOOKPROC(func)


# https://learn.microsoft.com/en-us/windows/console/handlerroutine
# BOOL WINAPI HandlerRoutine(
#   _In_ DWORD dwCtrlType
# );
_PHANDLER_ROUTINE = ctypes.WINFUNCTYPE(
    wintypes.BOOL,
    wintypes.DWORD
)


def PHANDLER_ROUTINE(func: Callable[[int], bool]) -> _PHANDLER_ROUTINE:
    return _PHANDLER_ROUTINE(func)


KERNEL32 = ctypes.WinDLL('kernel32', use_last_error = True)

# https://learn.microsoft.com/en-us/windows/console/setconsolectrlhandler
# BOOL WINAPI SetConsoleCtrlHandler(
#   _In_opt_ PHANDLER_ROUTINE HandlerRoutine,
#   _In_ BOOL Add
# );
SetConsoleCtrlHandler = KERNEL32.SetConsoleCtrlHandler
SetConsoleCtrlHandler.argtypes = (_PHANDLER_ROUTINE, wintypes.BOOL)
SetConsoleCtrlHandler.restype = wintypes.BOOL

# https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-getcurrentthreadid
# DWORD GetCurrentThreadId();
GetCurrentThreadId = KERNEL32.GetCurrentThreadId
GetCurrentThreadId.restype = wintypes.DWORD

USER32 = ctypes.WinDLL('user32', use_last_error = True)

# https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-setwindowshookexw
# HHOOK SetWindowsHookExW(
#   [in] int       idHook,
#   [in] HOOKPROC  lpfn,
#   [in] HINSTANCE hmod,
#   [in] DWORD     dwThreadId
# );
SetWindowsHookEx = USER32.SetWindowsHookExW
SetWindowsHookEx.argtypes = (ctypes.c_int, _HOOKPROC, wintypes.HINSTANCE, wintypes.DWORD)
SetWindowsHookEx.restype = wintypes.HHOOK

# https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-sendinput
# UINT SendInput(
#   [in] UINT    cInputs,
#   [in] LPINPUT pInputs,
#   [in] int     cbSize
# );
SendInput = USER32.SendInput
SendInput.argtypes = (wintypes.UINT, ctypes.c_voidp, wintypes.UINT)
SendInput.restype = None

# https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-vkkeyscanw
# SHORT VkKeyScanW(
#   [in] WCHAR ch
# );
VkKeyScan = USER32.VkKeyScanW
VkKeyScan.argtypes = (wintypes.WCHAR, )
VkKeyScan.restype = wintypes.SHORT

# UINT MapVirtualKeyW(
#   [in] UINT uCode,
#   [in] UINT uMapType
# );
MapVirtualKey = USER32.MapVirtualKeyW
MapVirtualKey.argtypes = (wintypes.UINT, wintypes.UINT)
MapVirtualKey.restype = wintypes.UINT

# https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-callnexthookex
# LRESULT CallNextHookEx(
#   [in, optional] HHOOK  hhk,
#   [in]           int    nCode,
#   [in]           WPARAM wParam,
#   [in]           LPARAM lParam
# );
CallNextHookEx = USER32.CallNextHookEx
CallNextHookEx.argtypes = (wintypes.HHOOK, ctypes.c_int, wintypes.WPARAM, wintypes.LPARAM)
CallNextHookEx.restype = ctypes.c_ssize_t

# https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-unhookwindowshookex
# BOOL UnhookWindowsHookEx(
#   [in] HHOOK hhk
# );
UnhookWindowsHookEx = USER32.UnhookWindowsHookEx
UnhookWindowsHookEx.argtypes = (wintypes.HHOOK,)
UnhookWindowsHookEx.restype = wintypes.BOOL

# https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-getkeyboardstate
# BOOL GetKeyboardState(
#   [out] PBYTE lpKeyState
# );
GetKeyboardState = USER32.GetKeyboardState
GetKeyboardState.argtypes = (ctypes.POINTER(ctypes.c_ubyte * 256),)
GetKeyboardState.restype = wintypes.BOOL

# https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-tounicode
# int ToUnicode(
#   [in]           UINT  wVirtKey,
#   [in]           UINT  wScanCode,
#   [in, optional] const BYTE *lpKeyState,
#   [out]          LPWSTR  pwszBuff,
#   [in]           int   cchBuff,
#   [in]           UINT  wFlags
# );
ToUnicode = USER32.ToUnicode
ToUnicode.argtypes = (wintypes.UINT, wintypes.UINT, ctypes.POINTER(ctypes.c_ubyte * 256), wintypes.LPWSTR, ctypes.c_int, wintypes.UINT)
ToUnicode.restype = ctypes.c_int

# https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-getmessagew
# BOOL GetMessageW(
#   [out]          LPMSG lpMsg,
#   [in, optional] HWND  hWnd,
#   [in]           UINT  wMsgFilterMin,
#   [in]           UINT  wMsgFilterMax
# );
GetMessage = USER32.GetMessageW
GetMessage.argtypes = (wintypes.LPMSG, wintypes.HWND, wintypes.UINT, wintypes.UINT)
GetMessage.restype = wintypes.BOOL

# https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-postthreadmessagew
# BOOL PostThreadMessageW(
#   [in] DWORD  idThread,
#   [in] UINT   Msg,
#   [in] WPARAM wParam,
#   [in] LPARAM lParam
# );
PostThreadMessage = USER32.PostThreadMessageW
PostThreadMessage.argtypes = (wintypes.DWORD, wintypes.UINT, wintypes.WPARAM, wintypes.LPARAM)
PostThreadMessage.restype = wintypes.BOOL

# https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-peekmessagew
# BOOL PeekMessageW(
#   [out]          LPMSG lpMsg,
#   [in, optional] HWND  hWnd,
#   [in]           UINT  wMsgFilterMin,
#   [in]           UINT  wMsgFilterMax,
#   [in]           UINT  wRemoveMsg
# );
PeekMessage = USER32.PeekMessageW
PeekMessage.argtypes = (wintypes.LPMSG, wintypes.HWND, wintypes.UINT, wintypes.UINT, wintypes.UINT)
PeekMessage.restype = wintypes.BOOL


def to_unicode(vk: int, scan_code: int) -> tuple[int, str]:
    buffer_size = 8
    output_buffer = ctypes.create_unicode_buffer(buffer_size)

    key_state = (ctypes.c_ubyte * 256)()
    GetKeyboardState(ctypes.byref(key_state))

    result = ToUnicode(vk, scan_code, ctypes.byref(key_state), output_buffer, buffer_size, 0)
    translated_char = output_buffer.value if result > 0 else ""

    return result, translated_char
# endregion


# @formatter:off
# https://learn.microsoft.com/en-us/windows/win32/winmsg/about-messages-and-message-queues#system-defined-messages
class WM(IntEnum):
    USER       = 0x0400

    # https://learn.microsoft.com/en-us/windows/win32/inputdev/keyboard-input-notifications
    KEYDOWN    = 0x0100
    SYSKEYDOWN = 0x0104

    # https://learn.microsoft.com/en-us/windows/win32/winmsg/window-notifications
    QUIT       = 0x0012


class WH(IntEnum):
    # https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-setwindowshookexw
    KEYBOARD_LL = 13


class CtrlType(IntEnum):
    CTRL_C_EVENT     = 0
    CTRL_BREAK_EVENT = 1
    CTRL_CLOSE_EVENT = 2
# @formatter:on


# --- Setup Graceful Shutdown ---
THREADID = GetCurrentThreadId()


@PHANDLER_ROUTINE
def console_handler(dwCtrlType: int):
    try:
        ctrl_type = CtrlType(dwCtrlType)
        print(f"\nShutdown signal detected {ctrl_type.name!r}.\nIssuing 'WM_QUIT' message via 'PostThreadMessage'...")
        PostThreadMessage(THREADID, WM.QUIT, 0, 0)
        return True  # Tell Windows we handled the signal

    except ValueError:
        return False


# Register the handler with Windows
SetConsoleCtrlHandler(console_handler, True)


# --- The Hook Callback ---
@HOOKPROC
def hook_callback(nCode: int, wParam: int, lParam: int):
    if nCode >= 0:
        if wParam in {WM.KEYDOWN, WM.SYSKEYDOWN}:
            kbd_struct = ctypes.cast(lParam, ctypes.POINTER(KBDLLHOOKSTRUCT)).contents
            vk_code = kbd_struct.vkCode
            scan_code = kbd_struct.scanCode

            result, char_typed = to_unicode(vk_code, scan_code)

            if result > 0:
                # Block the 'A' key (Virtual-Key Code 0x41)
                blocked = vk_code == 0x41

                print(f"{'blocked ' if blocked else ''}key pressed: 0x{vk_code:X} | Translated String: {char_typed!r}")  # !r invokes repr() to safely escape non-printable keys

                if blocked:
                    return 1  # Non-zero return blocks the input

            else:
                print(f"Key pressed: 0x{vk_code:X} | (Non-printable key)")

    # Pass the event to the next hook in the chain
    return CallNextHookEx(None, nCode, wParam, lParam)


# --- Set the Hook ---
hook_id = SetWindowsHookEx(
    WH.KEYBOARD_LL,
    hook_callback,
    None,  # hMod is NULL for WH_KEYBOARD_LL if the hook is in the same process
    0  # dwThreadId is 0 to monitor all threads globally
)

if not hook_id:
    print("Failed to install hook.")
    sys.exit(1)

print("Hook installed. Listening for keystrokes. Press `CTRL+C | CTRL+BREAK` in terminal to exit (though 'A' won't type).")

# --- Message Loop ---
msg = wintypes.MSG()
lpmsg = ctypes.byref(msg)

# Windows uses lazy memory allocation for thread queues.
# We query WM_USER to forcefully allocate the queue in RAM before listening.
PeekMessage(lpmsg, None, WM.USER, WM.USER, 0)

while True:
    # GetMessage acts as a zero-CPU thread blocker.
    # It sleeps natively at the OS level until PostThreadMessage drops WM_QUIT.
    result = GetMessage(lpmsg, None, 0, 0)
    if result <= 0 or msg.message == WM.QUIT:
        break

# --- Cleanup ---
UnhookWindowsHookEx(hook_id)

Limitations and Exceptions

While WH_KEYBOARD_LL is highly effective, it has a few architectural limits inherent to how Windows manages security and input isolation:

• Secure Attention Sequence (SAS): You cannot block Ctrl + Alt + Del. This sequence is hardwired into the Windows kernel to trigger Winlogon. User-mode hooks are explicitly bypassed to prevent malicious software from spoofing the lock screen.
• DirectInput & Raw Input (Gaming): Many modern games and game engines (like Unreal Engine) use DirectInput or Raw Input APIs to read directly from the hardware buffers, bypassing the standard Windows message queue. A WH_KEYBOARD_LL hook might fail to block keystrokes in these applications because the game is polling the driver directly, rather than waiting for WM_KEYDOWN messages.
• High IL (Integrity Level) Processes: If your script is running as a standard user, it cannot intercept or block keystrokes when the active foreground window is running as Administrator (Elevated). To hook inputs globally across all windows, your hook process must also be running with Administrator privileges.

To intercept keys before the OS kernel or to bypass DirectInput entirely, you would have to leave the Win32 API behind and write a custom Kernel-Mode Keyboard Filter Driver (a .sys file), which sits directly above the kbdclass driver in the driver stack.