Windows Curses Support

2.4.2 · active · verified Thu Apr 16

The `windows-curses` library provides a compatible implementation of the standard Python `curses` module for Microsoft Windows environments. It enables the creation of text-based user interfaces (TUIs) on Windows, bridging the gap as the native `curses` module is Unix-only. Currently at version 2.4.2, it sees active development with regular updates for new Python versions.

Common errors

```
ModuleNotFoundError: No module named '_curses'
```
cause The Python `curses` module is not available by default on Windows. Although `windows-curses` provides it, the package might not be installed or the Python environment is misconfigured.

fix Ensure `windows-curses` is installed in your active Python environment: `pip install windows-curses`. If using a virtual environment, activate it first.
```
AttributeError: 'module' object has no attribute 'initscr' (most likely due to a circular import)
```
cause Your Python script is likely named `curses.py`, which conflicts with the imported `curses` module, causing Python to import your local file instead of the actual library.

fix Rename your Python script file to something other than `curses.py` (e.g., `my_app.py`).
```
AttributeError: module 'curses' has no attribute 'LINES'
```
cause The `curses.LINES` (or `curses.COLS`) attribute is only populated after the curses environment has been initialized, typically by calling `curses.initscr()` or `curses.wrapper()`.

fix Access `curses.LINES` and `curses.COLS` only after `curses.initscr()` has been called. If using `curses.wrapper`, ensure the access happens inside the function passed to `wrapper`.
```
Program runs but immediately exits or does nothing (Python 3.12)
```
cause Specific compatibility issues with `windows-curses` and Python 3.12 cause applications to fail silently.

fix Downgrade your Python installation to version 3.11, or check for a new `windows-curses` release that explicitly lists Python 3.12 support. (Python 3.13 and 3.14 are supported by recent versions).

Warnings

breaking The `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.
Fix: Downgrade 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.
gotcha Naming your Python script `curses.py` will cause a circular import, leading to `AttributeError` when trying to call `curses.initscr()` or other curses functions.
Fix: Rename your Python file to something other than `curses.py` (e.g., `my_curses_app.py`).
gotcha Attributes 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`.
Fix: Ensure `curses.initscr()` has executed before accessing `curses.LINES` or `curses.COLS`. If using `wrapper`, access these within the main function passed to `wrapper`.
gotcha Curses 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.
Fix: Run your `curses` application directly from an external command prompt or PowerShell, rather than the IDE's integrated terminal.
gotcha For `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.
Fix: For 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.

Install

pip install windows-curses Install latest version

Imports

curses
wrong:
```
import _curses
```
correct:
```
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.

Quickstart

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)

view raw JSON →