{"id":8781,"library":"windows-curses","title":"Windows Curses Support","description":"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.","status":"active","version":"2.4.2","language":"en","source_language":"en","source_url":"https://github.com/zephyrproject-rtos/windows-curses","tags":["Windows","curses","TUI","terminal UI","console"],"install":[{"cmd":"pip install windows-curses","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"The `windows-curses` package installs the `_curses` module, allowing the standard `import curses` to function on Windows. Do not attempt to import `_curses` directly.","wrong":"import _curses","symbol":"curses","correct":"import curses"},{"note":"The `wrapper` function from `curses` is highly recommended for handling initialization and cleanup of the curses environment.","symbol":"wrapper","correct":"from curses import wrapper"}],"quickstart":{"code":"import curses\nfrom curses import wrapper\n\ndef main(stdscr):\n    # Clear screen\n    stdscr.clear()\n\n    # Display a simple message\n    stdscr.addstr(0, 0, \"Hello from windows-curses!\")\n    stdscr.addstr(1, 0, \"Press any key to exit.\")\n\n    # Refresh the screen to show changes\n    stdscr.refresh()\n\n    # Wait for user input\n    stdscr.getch()\n\nif __name__ == '__main__':\n    wrapper(main)","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=3.12.0, <3.13.0 (fixed in 2.4.1 for 3.13 and 2.4.2 for 3.14)"},{"fix":"Rename your Python file to something other than `curses.py` (e.g., `my_curses_app.py`).","message":"Naming your Python script `curses.py` will cause a circular import, leading to `AttributeError` when trying to call `curses.initscr()` or other curses functions.","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"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`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Run your `curses` application directly from an external command prompt or PowerShell, rather than the IDE's integrated terminal.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<2.0.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure `windows-curses` is installed in your active Python environment: `pip install windows-curses`. If using a virtual environment, activate it first.","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.","error":"ModuleNotFoundError: No module named '_curses'"},{"fix":"Rename your Python script file to something other than `curses.py` (e.g., `my_app.py`).","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.","error":"AttributeError: 'module' object has no attribute 'initscr' (most likely due to a circular import)"},{"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`.","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()`.","error":"AttributeError: module 'curses' has no attribute 'LINES'"},{"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).","cause":"Specific compatibility issues with `windows-curses` and Python 3.12 cause applications to fail silently.","error":"Program runs but immediately exits or does nothing (Python 3.12)"}]}