Install & Compatibility
Where this runs
tested against v? · pip install
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.920 runs
build_error
glibcpy 3.10–3.920 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
curses
✓ import curses
✗ import _curses
The `windows-curses` package installs the `_curses` module, allowing the standard `import curses` to function on Windows. Do not attempt to import `_curses` directly.
wrapper
✓ from curses import wrapper
The `wrapper` function from `curses` is highly recommended for handling initialization and cleanup of the curses environment.
This quickstart demonstrates the basic setup and use of `windows-curses`. It initializes the curses environment, displays a simple 'Hello World' message, waits for a key press, and then cleans up. The `curses.wrapper` function is used for robust initialization and cleanup.
import curses
from curses import wrapper
def main(stdscr):
# Clear screen
stdscr.clear()
# Display a simple message
stdscr.addstr(0, 0, "Hello from windows-curses!")
stdscr.addstr(1, 0, "Press any key to exit.")
# Refresh the screen to show changes
stdscr.refresh()
# Wait for user input
stdscr.getch()
if __name__ == '__main__':
wrapper(main)
Debug
Known issues
breakingThe `windows-curses` package has known compatibility issues with Python 3.12, where it may install but programs using it will silently exit or do nothing.fixDowngrade to Python 3.11 or wait for an official `windows-curses` release that explicitly supports Python 3.12. Versions 2.4.1 and 2.4.2 added support for Python 3.13 and 3.14 respectively, but 3.12 might still be problematic if not explicitly addressed.
affects: >=3.12.0, <3.13.0 (fixed in 2.4.1 for 3.13 and 2.4.2 for 3.14)
gotchaNaming your Python script `curses.py` will cause a circular import, leading to `AttributeError` when trying to call `curses.initscr()` or other curses functions.fixRename your Python file to something other than `curses.py` (e.g., `my_curses_app.py`).
affects: All versions
gotchaAttributes like `curses.LINES` and `curses.COLS` are only defined after `curses.initscr()` (or `curses.wrapper`) has been called. Attempting to access them before initialization will result in an `AttributeError`.fixEnsure `curses.initscr()` has executed before accessing `curses.LINES` or `curses.COLS`. If using `wrapper`, access these within the main function passed to `wrapper`.
affects: All versions
gotchaCurses applications, even with `windows-curses`, may not function correctly or display properly when run within integrated terminals of IDEs like VS Code or PyCharm, but often work fine in a standalone Windows Command Prompt or PowerShell.fixRun your `curses` application directly from an external command prompt or PowerShell, rather than the IDE's integrated terminal.
affects: All versions
gotchaFor `windows-curses` versions prior to 2.0, automatic terminal resizing (similar to `SIGWINCH` on Unix-like systems) for applications developed against ncurses might not work out-of-the-box.fixFor older versions, you might need to manually call `curses.resize_term(0, 0)` after receiving `KEY_RESIZE` from `getch()`, `getkey()`, or `get_wch()`, wrapping the call in a `try...except curses.error` block. Versions 2.0+ include a hack to handle this automatically.
affects: <2.0.0
Upgrade
Version history
2.4.2latest on PyPI · released Mar 31, 2026
Audit
Dependencies
No dependency data recorded yet.