0
# Pynput
1

2
A Python library that provides comprehensive control and monitoring capabilities for user input devices including mouse and keyboard interactions across multiple operating systems (Windows, macOS, Linux). Pynput offers both high-level control interfaces for simulating mouse movements, clicks, scrolls and keyboard input, as well as event listeners for monitoring and responding to user input events in real-time.
3

4
## Package Information
5

6
- **Package Name**: pynput
7
- **Language**: Python
8
- **Installation**: `pip install pynput`
9

10
**Platform-specific dependencies:**
11

12
- **macOS**: Requires PyObjC frameworks: `pyobjc-framework-ApplicationServices >=8.0`, `pyobjc-framework-Quartz >=8.0`
13
- **Linux**: Requires `evdev >= 1.3`, `python-xlib >= 0.17`
14
- **Windows**: No additional dependencies (uses built-in win32 APIs)
15

16
## Core Imports
17

18
```python
19
import pynput
20
from pynput import mouse, keyboard
21
```
22

23
Common imports for specific functionality:
24

25
```python
26
from pynput.mouse import Button, Controller as MouseController, Listener as MouseListener
27
from pynput.keyboard import Key, KeyCode, Controller as KeyboardController, Listener as KeyboardListener
28
```
29

30
## Basic Usage
31

32
```python
33
from pynput import mouse, keyboard
34
import time
35

36
# Mouse control example
37
mouse_controller = mouse.Controller()
38

39
# Get current position
40
print(f"Current position: {mouse_controller.position}")
41

42
# Move mouse to specific position
43
mouse_controller.position = (100, 100)
44

45
# Click left button
46
mouse_controller.click(mouse.Button.left)
47

48
# Keyboard control example
49
keyboard_controller = keyboard.Controller()
50

51
# Press and release a key
52
keyboard_controller.press('a')
53
keyboard_controller.release('a')
54

55
# Type a string
56
keyboard_controller.type('Hello World')
57

58
# Press special keys
59
keyboard_controller.press(keyboard.Key.enter)
60
keyboard_controller.release(keyboard.Key.enter)
61

62
# Mouse monitoring example
63
def on_click(x, y, button, pressed):
64
    print(f'{"Pressed" if pressed else "Released"} {button} at ({x}, {y})')
65
    if not pressed:
66
        # Stop listener
67
        return False
68

69
with mouse.Listener(on_click=on_click) as listener:
70
    listener.join()
71

72
# Keyboard monitoring example
73
def on_key_press(key):
74
    print(f'Key {key} pressed')
75
    if key == keyboard.Key.esc:
76
        return False
77

78
with keyboard.Listener(on_press=on_key_press) as listener:
79
    listener.join()
80
```
81

82
## Architecture
83

84
Pynput uses a cross-platform architecture with platform-specific backends:
85

86
- **Controllers**: Classes for sending synthetic input events (mouse movements, clicks, key presses)
87
- **Listeners**: Thread-based event listeners for monitoring real user input
88
- **Backend System**: Automatic platform detection (Windows: win32, macOS: darwin, Linux: xorg)
89
- **Event Classes**: Structured event objects for synchronous event processing
90

91
The library automatically selects the appropriate backend based on the operating system, providing consistent API across platforms while leveraging platform-specific optimizations.
92

93
## Capabilities
94

95
### Mouse Control and Monitoring
96

97
Comprehensive mouse input simulation and monitoring including position control, button clicks, scrolling, and real-time event listening. Supports all standard mouse buttons and scroll wheel interactions.
98

99
```python { .api }
100
class Controller:
101
    def __init__(self): ...
102

103
    @property
104
    def position(self) -> tuple[int, int]: ...
105

106
    @position.setter
107
    def position(self, pos: tuple[int, int]): ...
108

109
    def move(self, dx: int, dy: int): ...
110
    def click(self, button: Button, count: int = 1): ...
111
    def press(self, button: Button): ...
112
    def release(self, button: Button): ...
113
    def scroll(self, dx: int, dy: int): ...
114

115
class Listener:
116
    def __init__(
117
        self,
118
        on_move: callable = None,
119
        on_click: callable = None,
120
        on_scroll: callable = None,
121
        suppress: bool = False,
122
        **kwargs
123
    ): ...
124

125
    def start(self): ...
126
    def stop(self): ...
127
    def join(self, timeout: float = None): ...
128

129
class Button(enum.Enum):
130
    left = 1
131
    middle = 2
132
    right = 3
133
    unknown = 0
134
```
135

136
[Mouse Control and Monitoring](./mouse.md)
137

138
### Keyboard Control and Monitoring
139

140
Full keyboard input simulation and monitoring including individual key presses, string typing, modifier key combinations, and hotkey support. Handles both character keys and special keys across different layouts.
141

142
```python { .api }
143
class Controller:
144
    def __init__(self): ...
145

146
    def press(self, key: Key | KeyCode | str): ...
147
    def release(self, key: Key | KeyCode | str): ...
148
    def tap(self, key: Key | KeyCode | str): ...
149
    def type(self, string: str): ...
150
    def pressed(self, *keys) -> ContextManager: ...
151

152
class Listener:
153
    def __init__(
154
        self,
155
        on_press: callable = None,
156
        on_release: callable = None,
157
        suppress: bool = False,
158
        **kwargs
159
    ): ...
160

161
    def start(self): ...
162
    def stop(self): ...
163
    def join(self, timeout: float = None): ...
164

165
class KeyCode:
166
    def __init__(self, vk: int = None, char: str = None, is_dead: bool = False): ...
167

168
    @classmethod
169
    def from_vk(cls, vk: int) -> 'KeyCode': ...
170

171
    @classmethod
172
    def from_char(cls, char: str) -> 'KeyCode': ...
173

174
    @classmethod
175
    def from_dead(cls, char: str) -> 'KeyCode': ...
176

177
class HotKey:
178
    def __init__(self, keys: set, on_activate: callable): ...
179

180
    @staticmethod
181
    def parse(keys: str) -> list: ...
182

183
    def press(self, key): ...
184
    def release(self, key): ...
185

186
class GlobalHotKeys(Listener):
187
    def __init__(self, hotkeys: dict, *args, **kwargs): ...
188
```
189

190
[Keyboard Control and Monitoring](./keyboard.md)
191

192
## Cross-Platform Support
193

194
Pynput automatically detects the operating system and loads the appropriate backend:
195

196
- **Windows**: Uses win32 API for optimal performance and compatibility
197
- **macOS**: Uses Quartz Event Services and ApplicationServices framework
198
- **Linux**: Uses X11 (Xorg) for input handling and monitoring
199

200
Platform-specific options can be passed to listeners using prefixed parameters (e.g., `darwin_intercept`, `win32_event_filter`, `xorg_*`).
201

202
## Error Handling
203

204
Common exceptions include:
205

206
- `Controller.InvalidKeyException`: Raised when invalid key parameters are passed
207
- `Controller.InvalidCharacterException`: Raised when untypable characters are encountered
208
- `StopException`: Can be raised in listener callbacks to stop the listener
209
- `ImportError`: Raised when platform dependencies are missing
210

211
The library includes helpful resolution messages for platform-specific dependency issues.