Install & Compatibility
Where this runs
tested against v4.2.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.925 runs
installs and imports cleanly · install 0.0s · import 0.123s · 17.9MB
glibcpy 3.10–3.925 runs
installs and imports cleanly · install 1.5s · import 0.106s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
readchar
✓ from readchar import readchar
Main function to read a single character.
readkey
✓ from readchar import readkey
Function to read a key stroke, including special keys.
Key
✓ from readchar import Key
Enum representing special keys (e.g., Key.UP, Key.ENTER).
This quickstart demonstrates how to use `readchar()` to get a single character and `readkey()` to capture individual key strokes, including special keys represented by the `Key` enum. It also shows how to differentiate between regular characters and special keys when using `readkey()`.
from readchar import readchar, readkey, Key
import sys
print("Press any key to read a char (e.g., 'a', 'b', '1'): ", end="", flush=True)
char_input = readchar()
print(f"\nYou pressed: '{char_input}'")
print("\nPress a key (e.g., 'Enter', 'Space', 'Arrow Up'): ", end="", flush=True)
key_input = readkey()
if isinstance(key_input, Key):
print(f"\nYou pressed a special key: {key_input.name}")
else:
print(f"\nYou pressed a regular key: '{key_input}'")
print("\nExiting.")
Debug
Known issues
breakingreadchar dropped support for Python 3.6 in v4.0.4 and Python 3.7 in v4.0.6. If you are using these EOL Python versions, you must pin an older version of readchar.fixUpgrade to Python 3.8+ or pin `readchar` to a compatible version (e.g., `readchar<4.0.4` for Python 3.6, `readchar<4.0.6` for Python 3.7).
affects: <4.0.4 (for Python 3.6), <4.0.6 (for Python 3.7)
breakingUnicode support was significantly improved and implemented in v4.2.0. Prior versions might not correctly handle or display non-ASCII characters, leading to unexpected behavior or errors.fixEnsure you are using `readchar` version 4.2.0 or newer to guarantee proper handling of Unicode input.
affects: <4.2.0
gotcha`readchar()` and `readkey()` return different types of values. `readchar()` always returns a single-character string. `readkey()` returns a `Key` enum member for special keys (like `Key.UP`, `Key.ENTER`) and a string for regular characters. Mixing them up without type checking is a common mistake.fixWhen using `readkey()`, always check the type of the returned value (e.g., `isinstance(key_input, Key)`) to handle special keys and regular characters appropriately. Use `readchar()` when you explicitly only expect a single printable character.
affects: All versions
gotchaBoth `readchar()` and `readkey()` are blocking functions. They will pause program execution until a key is pressed. This might not be suitable for applications requiring non-blocking input without additional asynchronous programming or threading.fixFor non-blocking input, consider using a different library or integrating `readchar` within a separate thread or an asyncio event loop, possibly combined with a timeout mechanism if available (not directly provided by `readchar`).
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'readchar'
The 'readchar' library has not been installed in the current Python environment.
TypeError: 'module' object is not callable
The 'readchar' module was imported (`import readchar`) and then incorrectly called directly as a function (`readchar()`) instead of calling its specific functions like `readchar.readchar()` or `readchar.readkey()`.
fixCall the appropriate function, e.g., `char = readchar.readchar()` or `key = readchar.readkey()`.
NameError: name 'Key' is not defined
The `Key` enum, which provides symbolic names for special keys, was used without being explicitly imported from the `readchar` library.
fixImport `Key` alongside `readkey`, for example: `from readchar import readkey, Key`.
termios.error: (25, 'Inappropriate ioctl for device')
The script is being run in an environment that does not provide a true interactive terminal (TTY), which `readchar` requires for its low-level input functions.
fixExecute the Python script directly in an interactive shell or command prompt, not within an IDE's output pane or a non-interactive environment.
AttributeError: module 'readchar' has no attribute 'read_char'
The user is attempting to call a function named `read_char` (with an underscore) which does not exist in the `readchar` library; the correct function name is `readchar` (without an underscore, as `readchar.readchar()`).
fixUse the correct function name: `char = readchar.readchar()`.
Upgrade
Version history
4.2.2latest on PyPI · released Apr 6, 2026
Audit
Dependencies
No dependency data recorded yet.