# moses-palmer/pynput architecture

> Architecture diagram of the GitHub repository moses-palmer/pynput, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/moses-palmer/pynput
- Repository: https://github.com/moses-palmer/pynput

## Overview

pynput is a Python library for controlling and monitoring keyboard and mouse input. An application chooses a device API, creates a controller to emit input or a listener to observe it, and receives callbacks or queued events. The keyboard and mouse APIs share listener lifecycle and platform-selection utilities, then rely on operating-system-specific backends. The tree documents backends for macOS, Windows, Xorg, and Linux uinput; sampled source directly supports only parts of the common layer and Windows/Xorg implementations, so unsampled backend details are represented at module level.

Main entry points: [`lib/pynput/keyboard/__init__.py`](https://github.com/moses-palmer/pynput/blob/master/lib/pynput/keyboard/__init__.py) (Keyboard API), [`lib/pynput/mouse/__init__.py`](https://github.com/moses-palmer/pynput/blob/master/lib/pynput/mouse/__init__.py) (Mouse API), [`lib/pynput/_util/__init__.py`](https://github.com/moses-palmer/pynput/blob/master/lib/pynput/_util/__init__.py) (Runtime utilities), [`lib/pynput/keyboard/_xorg.py`](https://github.com/moses-palmer/pynput/blob/master/lib/pynput/keyboard/_xorg.py) (Xorg keyboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Device APIs"]
  node_keyboard_api["Keyboard API<br/>[__init__.py]"]
  node_mouse_api["Mouse API<br/>[__init__.py]"]
end

subgraph group_shared["Shared Runtime"]
  node_key_base["Key base<br/>[_base.py]"]
  node_mouse_base["Mouse base<br/>[_base.py]"]
  node_runtime_util["Runtime utilities<br/>[__init__.py]"]
  node_win_util["Windows utilities<br/>[win32.py]"]
  node_xorg_util["Xorg utilities<br/>[xorg.py]"]
  node_xorg_symbols["Xorg key symbols<br/>[xorg_keysyms.py]"]
end

subgraph group_keyboard["Keyboard Backends"]
  node_mac_key["macOS keyboard<br/>[_darwin.py]"]
  node_win_key["Windows keyboard<br/>[_win32.py]"]
  node_xorg_key["Xorg keyboard<br/>[_xorg.py]"]
  node_uinput_key["uinput keyboard<br/>[_uinput.py]"]
  node_dummy_key["Dummy keyboard<br/>[_dummy.py]"]
end

subgraph group_mouse["Mouse Backends"]
  node_mac_mouse["macOS mouse<br/>[_darwin.py]"]
  node_win_mouse["Windows mouse<br/>[_win32.py]"]
  node_xorg_mouse["Xorg mouse<br/>[_xorg.py]"]
  node_dummy_mouse["Dummy mouse<br/>[_dummy.py]"]
end

node_application(("Application"))
node_os_input{{"Operating system input"}}

node_application -->|"uses keyboard"| node_keyboard_api
node_application -->|"uses mouse"| node_mouse_api
node_keyboard_api -->|"selects backend"| node_runtime_util
node_mouse_api -->|"selects backend"| node_runtime_util
node_keyboard_api -->|"uses common API"| node_key_base
node_mouse_api -->|"uses common API"| node_mouse_base
node_key_base -->|"uses listener runtime"| node_runtime_util
node_mouse_base -->|"uses listener runtime"| node_runtime_util
node_runtime_util -->|"uses Windows support"| node_win_util
node_runtime_util -->|"uses Xorg support"| node_xorg_util
node_keyboard_api -->|"dispatches"| node_mac_key
node_keyboard_api -->|"dispatches"| node_win_key
node_keyboard_api -->|"dispatches"| node_xorg_key
node_keyboard_api -->|"dispatches"| node_uinput_key
node_keyboard_api -->|"dispatches"| node_dummy_key
node_mouse_api -->|"dispatches"| node_mac_mouse
node_mouse_api -->|"dispatches"| node_win_mouse
node_mouse_api -->|"dispatches"| node_xorg_mouse
node_mouse_api -->|"dispatches"| node_dummy_mouse
node_key_base -->|"emits or receives"| node_os_input
node_mouse_base -->|"emits or receives"| node_os_input
node_win_key -->|"uses hooks"| node_win_util
node_win_mouse -->|"uses hooks"| node_win_util
node_xorg_key -->|"uses Xorg"| node_xorg_util
node_xorg_key -->|"maps key symbols"| node_xorg_symbols
node_xorg_mouse -->|"uses Xorg"| node_xorg_util
node_mac_key -->|"emits or monitors"| node_os_input
node_win_key -->|"emits or monitors"| node_os_input
node_xorg_key -->|"emits or monitors"| node_os_input
node_uinput_key -->|"emits or monitors"| node_os_input
node_mac_mouse -->|"emits or monitors"| node_os_input
node_win_mouse -->|"emits or monitors"| node_os_input
node_xorg_mouse -->|"emits or monitors"| node_os_input

click node_keyboard_api "https://github.com/moses-palmer/pynput/blob/master/lib/pynput/keyboard/__init__.py"
click node_mouse_api "https://github.com/moses-palmer/pynput/blob/master/lib/pynput/mouse/__init__.py"
click node_key_base "https://github.com/moses-palmer/pynput/blob/master/lib/pynput/keyboard/_base.py"
click node_mouse_base "https://github.com/moses-palmer/pynput/blob/master/lib/pynput/mouse/_base.py"
click node_runtime_util "https://github.com/moses-palmer/pynput/blob/master/lib/pynput/_util/__init__.py"
click node_win_util "https://github.com/moses-palmer/pynput/blob/master/lib/pynput/_util/win32.py"
click node_xorg_util "https://github.com/moses-palmer/pynput/blob/master/lib/pynput/_util/xorg.py"
click node_xorg_symbols "https://github.com/moses-palmer/pynput/blob/master/lib/pynput/_util/xorg_keysyms.py"
click node_mac_key "https://github.com/moses-palmer/pynput/blob/master/lib/pynput/keyboard/_darwin.py"
click node_win_key "https://github.com/moses-palmer/pynput/blob/master/lib/pynput/keyboard/_win32.py"
click node_xorg_key "https://github.com/moses-palmer/pynput/blob/master/lib/pynput/keyboard/_xorg.py"
click node_uinput_key "https://github.com/moses-palmer/pynput/blob/master/lib/pynput/keyboard/_uinput.py"
click node_dummy_key "https://github.com/moses-palmer/pynput/blob/master/lib/pynput/keyboard/_dummy.py"
click node_mac_mouse "https://github.com/moses-palmer/pynput/blob/master/lib/pynput/mouse/_darwin.py"
click node_win_mouse "https://github.com/moses-palmer/pynput/blob/master/lib/pynput/mouse/_win32.py"
click node_xorg_mouse "https://github.com/moses-palmer/pynput/blob/master/lib/pynput/mouse/_xorg.py"
click node_dummy_mouse "https://github.com/moses-palmer/pynput/blob/master/lib/pynput/mouse/_dummy.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_keyboard_api,node_mouse_api toneBlue
class node_key_base,node_mouse_base,node_runtime_util,node_win_util,node_xorg_util,node_xorg_symbols toneAmber
class node_mac_key,node_win_key,node_xorg_key,node_uinput_key,node_dummy_key toneMint
class node_mac_mouse,node_win_mouse,node_xorg_mouse,node_dummy_mouse toneRose
class node_application,node_os_input toneIndigo
```

## Components

### Device APIs

- [Keyboard API](https://github.com/moses-palmer/pynput/blob/master/lib/pynput/keyboard/__init__.py): `lib/pynput/keyboard/__init__.py`
- [Mouse API](https://github.com/moses-palmer/pynput/blob/master/lib/pynput/mouse/__init__.py): `lib/pynput/mouse/__init__.py`

### Shared Runtime

- [Key base](https://github.com/moses-palmer/pynput/blob/master/lib/pynput/keyboard/_base.py): `lib/pynput/keyboard/_base.py`
- [Mouse base](https://github.com/moses-palmer/pynput/blob/master/lib/pynput/mouse/_base.py): `lib/pynput/mouse/_base.py`
- [Runtime utilities](https://github.com/moses-palmer/pynput/blob/master/lib/pynput/_util/__init__.py): `lib/pynput/_util/__init__.py`
- [Windows utilities](https://github.com/moses-palmer/pynput/blob/master/lib/pynput/_util/win32.py): `lib/pynput/_util/win32.py`
- [Xorg utilities](https://github.com/moses-palmer/pynput/blob/master/lib/pynput/_util/xorg.py): `lib/pynput/_util/xorg.py`
- [Xorg key symbols](https://github.com/moses-palmer/pynput/blob/master/lib/pynput/_util/xorg_keysyms.py): `lib/pynput/_util/xorg_keysyms.py`

### Keyboard Backends

- [macOS keyboard](https://github.com/moses-palmer/pynput/blob/master/lib/pynput/keyboard/_darwin.py): `lib/pynput/keyboard/_darwin.py`
- [Windows keyboard](https://github.com/moses-palmer/pynput/blob/master/lib/pynput/keyboard/_win32.py): `lib/pynput/keyboard/_win32.py`
- [Xorg keyboard](https://github.com/moses-palmer/pynput/blob/master/lib/pynput/keyboard/_xorg.py): `lib/pynput/keyboard/_xorg.py`
- [uinput keyboard](https://github.com/moses-palmer/pynput/blob/master/lib/pynput/keyboard/_uinput.py): `lib/pynput/keyboard/_uinput.py`
- [Dummy keyboard](https://github.com/moses-palmer/pynput/blob/master/lib/pynput/keyboard/_dummy.py): `lib/pynput/keyboard/_dummy.py`

### Mouse Backends

- [macOS mouse](https://github.com/moses-palmer/pynput/blob/master/lib/pynput/mouse/_darwin.py): `lib/pynput/mouse/_darwin.py`
- [Windows mouse](https://github.com/moses-palmer/pynput/blob/master/lib/pynput/mouse/_win32.py): `lib/pynput/mouse/_win32.py`
- [Xorg mouse](https://github.com/moses-palmer/pynput/blob/master/lib/pynput/mouse/_xorg.py): `lib/pynput/mouse/_xorg.py`
- [Dummy mouse](https://github.com/moses-palmer/pynput/blob/master/lib/pynput/mouse/_dummy.py): `lib/pynput/mouse/_dummy.py`

### Other components

- **Application**
- **Operating system input**

## Connections

- Application → Keyboard API: uses keyboard
- Application → Mouse API: uses mouse
- Keyboard API → Runtime utilities: selects backend
- Mouse API → Runtime utilities: selects backend
- Keyboard API → Key base: uses common API
- Mouse API → Mouse base: uses common API
- Key base → Runtime utilities: uses listener runtime
- Mouse base → Runtime utilities: uses listener runtime
- Runtime utilities → Windows utilities: uses Windows support
- Runtime utilities → Xorg utilities: uses Xorg support
- Keyboard API → macOS keyboard: dispatches
- Keyboard API → Windows keyboard: dispatches
- Keyboard API → Xorg keyboard: dispatches
- Keyboard API → uinput keyboard: dispatches
- Keyboard API → Dummy keyboard: dispatches
- Mouse API → macOS mouse: dispatches
- Mouse API → Windows mouse: dispatches
- Mouse API → Xorg mouse: dispatches
- Mouse API → Dummy mouse: dispatches
- Key base → Operating system input: emits or receives
- Mouse base → Operating system input: emits or receives
- Windows keyboard → Windows utilities: uses hooks
- Windows mouse → Windows utilities: uses hooks
- Xorg keyboard → Xorg utilities: uses Xorg
- Xorg keyboard → Xorg key symbols: maps key symbols
- Xorg mouse → Xorg utilities: uses Xorg
- macOS keyboard → Operating system input: emits or monitors
- Windows keyboard → Operating system input: emits or monitors
- Xorg keyboard → Operating system input: emits or monitors
- uinput keyboard → Operating system input: emits or monitors
- macOS mouse → Operating system input: emits or monitors
- Windows mouse → Operating system input: emits or monitors
- Xorg mouse → Operating system input: emits or monitors