boppreh/keyboard: global keyboard hooks and simulated key presses in pure Python
Hook and simulate global keyboard events on Windows and Linux.
At a glance
- What is it?
- A pure Python library that hooks keyboard events system-wide on Windows and Linux, with hotkeys, recording, playback and no compiled dependencies. It is unmaintained and its Linux backend reads raw device files as root.
- Who is it for?
- Adopt boppreh/keyboard for internal Windows tooling, kiosk automation or Linux scripts where you control the machine and can run as root. Do not adopt it for cross-platform products, macOS targets, or anything a hostile user could turn into a keylogger, since the README states the library makes no attempt to hide itself.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 135 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 22, 2026, and from our analysis. They are not legal advice.
Star history
- boppreh/keyboard3,969 ★ · -1
| Repository | 2026-09-24 | 2026-11-22 |
|---|---|---|
| boppreh/keyboard | 4k | 4k |
-1 Stars in the last 59 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
What boppreh/keyboard actually solves
Most Python GUI toolkits only see keystrokes that arrive while one of their own windows has focus. boppreh/keyboard takes the opposite approach. It installs a global hook, so events reach your program regardless of which window is active, and it can also synthesize events so your program can type on the user's behalf. The README describes the feature set as a "Global event hook on all keyboards (captures keys regardless of focus)" together with listen and send support.
That combination covers a narrow but real set of jobs: push-to-talk bindings, macro recorders, kiosk shortcuts, automated test harnesses that must drive a real desktop, and accessibility tools that remap keys. The repository ships examples that map onto those jobs directly, including push_to_talk_ubuntu.py, segmented_macro.py, simulate_held_down.py and customizable_hotkey.py.
The audience is Python developers on Windows and Linux who need system-level input rather than widget-level input. If your program only needs to know what the user typed into its own text field, this library is heavier than the problem. It is also explicitly not for anything covert: the README says the program makes no attempt to hide itself and asks readers not to use it for keyloggers or online gaming bots.
How the hook, the event thread and the high level API fit together
The library is pure Python with zero dependencies, which shapes the whole design. Because there is no C extension, the platform-specific hooking has to be built from what the standard library exposes on each system. On Linux the README states that the implementation avoids depending on X and instead reads raw device files under /dev/input/input*, which is why root is required. On Windows the hook is a system-level keyboard hook, and that platform gets the extra capability of suppressing keys.
Events are captured on a separate thread, so the hook does not block the calling program. From there two layers sit on top. The low level layer is hook, on_press, read_event and the KeyboardEvent objects, which carry event_type, scan_code, name, time and is_keypad. The high level layer is built on the same stream: add_hotkey, record, play, add_abbreviation and wait. The standalone module form exposes the same stream as JSON lines, so `python -m keyboard` prints one object per event and the same output can be piped back in to replay it.
Hotkey parsing is worth noting because it is where the library spends its complexity budget. The README advertises "Complex hotkey support (e.g. ctrl+shift+m, ctrl+space) with controllable timeout", meaning a single registration can require a sequence of chords rather than one chord. Key names are resolved against the active layout, and the README claims full internationalization, giving Ctrl+ç as an example, plus a note that accented dead keys are not broken the way they are in pyHook. That last point is a direct comparison with an older Windows library, and it is the kind of problem that only shows up once someone types in a language other than English.
Install and a first working hotkey
The README gives two installation routes. The PyPI package is the short one, and the repository clone is offered because the source files are sufficient on their own, with no installation step required.
pip install keyboardIf you prefer the source, the README gives this alternative, and notes that the downloaded zip can simply be extracted into your project folder:
git clone https://github.com/boppreh/keyboardA first real use is registering a hotkey and keeping the process alive so the registration stays in effect. The README is explicit that if the program finishes, the hotkey is no longer in effect, and it warns against a bare `while True: pass` loop because that consumes 100% of a CPU core.
import keyboard
keyboard.add_hotkey('ctrl+shift+a', lambda: print('triggered'))
keyboard.wait('esc')When you run that, nothing prints until you press ctrl+shift+a, and the script exits when you press esc. On Linux, run it with sudo, because the README states the Linux implementation reads raw device files and therefore requires root. If you connect over SSH, the README warns that the connection forwards only typed text rather than keyboard events, so the remote process will never see your key presses.
For a quick look at the raw event stream without writing any code, the README documents a standalone mode. Redirecting stdout to a file captures JSON events until you interrupt the process, and feeding that file back in replays them:
python -m keyboard > events.txt
python -m keyboard < events.txtThe limitations that decide whether you can use it
The README lists its known limitations in plain terms, and several of them are disqualifying depending on the target. Key suppression, which is what you need to stop a keystroke from reaching the rest of the system, is only available on Windows. On Linux you can observe and synthesize, but you cannot swallow.
Media keys on Linux may arrive with no name, only a scan code, or not arrive at all. On Windows, generated events do not report a device id, so event.device is None. Both are recorded as open issues in the README, and neither has a documented workaround there.
Root on Linux is a design consequence, not an oversight: reading raw device files is how the library avoids depending on X. That means any Linux deployment has to accept either running the whole process as root or arranging device permissions yourself, and the README does not document a permission recipe.
The failure mode that is hardest to diagnose is other software. The README states that other applications, such as some games, may register hooks that swallow all key events, in which case the library will be unable to report events. From your program's point of view this looks identical to the user not pressing anything, so a hotkey that works on your desktop can silently do nothing on a machine running a game or another input-hooking tool.
The maintenance status is the last constraint. The README opens with a statement that the project is currently unmaintained, that it works for many cases, and that the author wishes to pick it up again in the future while warning about friction and limited features. The most recent tagged release is v0.13.5 from 2020-03-23, and the last push to the repository was on 2026-07-10. Development activity and releases have diverged for years, so treat the tagged package and the current master branch as different things.
Alternatives and where the approach differs
The README itself points at boppreh/mouse, a sibling project by the same author, installed with `pip install mouse`. The difference is scope rather than architecture: mouse covers pointer events, keyboard covers key events, and both follow the same pure Python, global hook model. If your automation needs to click as well as type, you would install both rather than replace one with the other.
For Windows-only work, the README's own comparison is pyHook, which it criticizes for breaking accented dead keys. That is the concrete difference: pyHook is a compiled Windows extension, while boppreh/keyboard is pure Python and therefore easier to vendor and deploy, at the cost of the platform coverage and suppression behavior you would get from a compiled Windows hook.
For cross-platform desktop automation, the practical alternative is a GUI automation framework built around accessibility APIs rather than raw input hooks. Those tools target widgets and windows by name, which is more stable than coordinates or raw scan codes, but they generally cannot see input directed at applications that expose no accessibility tree, and they are not designed for global hotkeys that fire while your own program is unfocused. The trade-off is the inverse of this library's: better semantics, less reach.
If your real requirement is a single global hotkey with no Python process attached, an OS-level shortcut or a small native helper is simpler than embedding an interpreter and a hook. This library earns its place when the hotkey logic is already Python and needs to share state with the rest of your program.
Maintenance, upgrades and the MIT licence
Upgrade cost here is mostly about drift between the released package and the repository. The latest release is v0.13.5 from 2020-03-23, preceded by v0.13.4 in 2019 and v0.13.3 in 2019, while the last push was on 2026-07-10. Anyone pinning `pip install keyboard` gets the 2020 code; anyone vendoring the master branch gets whatever has accumulated since, with no release notes describing it. The Makefile shows the release path is a manual sequence, running the test suite under both python2 and python, regenerating the README from docstrings through an external docstring2markdown script, then building the sdist and wheel. That external script is not in this repository, so the documented build target is not reproducible from a clone alone.
The README's unmaintained notice is the signal to plan around, not the commit dates. Expect no fixes for the open limitations listed above, and expect the documented Python 2 and 3 support to age as interpreter versions move on. setup.py still declares Python 2 and 3 classifiers and a Beta development status, which tells you what the packaging metadata was last written against.
The licence is MIT, declared in setup.py and present as LICENSE.txt at the repository root. MIT is permissive, so it permits commercial and closed-source use, modification and redistribution provided the copyright notice and permission notice are retained. That is a description of the licence text, not legal advice; if you are redistributing the library inside a product, have your own counsel confirm how the notice must be carried. One practical consequence of the pure Python design is that vendoring is genuinely feasible, since the README notes the source files are sufficient, but vendoring also means you inherit the maintenance burden the author has stepped back from.
Editorial conclusion
Adopt boppreh/keyboard for internal Windows tooling, kiosk automation or Linux scripts where you control the machine and can run as root. Do not adopt it for cross-platform products, macOS targets, or anything a hostile user could turn into a keylogger, since the README states the library makes no attempt to hide itself. Before committing, verify that your target applications do not install hooks that swallow key events, and confirm the exact Python version you need is supported by the current source, because the last tagged release is v0.13.5 from 2020-03-23.
Frequently asked questions
How do I install boppreh/keyboard?
The README gives `pip install keyboard` for the PyPI package, or a `git clone https://github.com/boppreh/keyboard` if you prefer the source. It notes that no installation is required for the clone because the source files are sufficient, and that the zip archive can be extracted into your project folder.
Does boppreh/keyboard work on Linux without root?
The README states that the Linux parts read raw device files under /dev/input/input* to avoid depending on X, and that this requires root. It does not document a non-root permission setup.
Can boppreh/keyboard block a key so other applications never see it?
Key suppression and blocking are listed in the README as available only on Windows. On Linux the library can report and simulate events, but the README does not claim the ability to swallow them.
Why does my hotkey stop working when the script ends?
The README explains that if the program finishes, the hotkey is not in effect anymore, and it recommends calling keyboard.wait() or sleeping in a loop instead of a bare busy loop. It also warns that a bare `while True: pass` will use 100% of your CPU.
Is boppreh/keyboard still maintained?
The README states the project is currently unmaintained and that the author wishes to pick it up again in the future, while warning about friction and limited features. The latest tagged release is v0.13.5 from 2020-03-23, and the last push to the repository was on 2026-07-10.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/boppreh-keyboard)Star history chart for your README
[](https://hysenlabs.com/projects/boppreh-keyboard)Was this useful?