Blessed

Common errors

• ModuleNotFoundError: No module named 'blessed'

  cause The 'blessed' package is not installed in the Python environment you are currently using, or there is a mismatch between how it was installed (e.g., using `pip`) and how the Python script is being executed (e.g., with a different Python interpreter).
  fix Ensure 'blessed' is installed for your active Python interpreter: `pip install blessed` or `python -m pip install blessed`.

• AttributeError: 'ParameterizingString' object has no attribute 'blink'

  cause The `blink` attribute was removed or changed in newer versions of the `blessed` library, or it might not be supported by your terminal, leading to an AttributeError when attempting to use it directly on a `Terminal` object's formatting strings.
  fix Use the `term.blink()` callable method or compound styling if your terminal supports blinking, and consult the current `blessed` documentation for the correct way to apply blinking, for example: `print(term.blink('Blinking Text'))`.

• ImportError: Blessed needs Python 3.2.3 or greater for Python 3

  cause You are attempting to use a version of `blessed` with a Python 3 interpreter that is older than the minimum required version (3.2.3), or the library's version check mechanism is misidentifying your Python version.
  fix Upgrade your Python 3 interpreter to version 3.2.3 or newer, or ensure you are running your script with an up-to-date Python 3 environment. If using a virtual environment, verify its Python version.

Warnings

• breaking Python 3.7 and earlier versions are no longer supported since Blessed version 1.28. Attempting to use Blessed 1.28+ with Python 3.7 or older will result in an ImportError.
  Fix: Upgrade your Python environment to 3.8 or newer. For projects requiring older Python versions, use Blessed < 1.28.
• deprecated The `Terminal.move()` method is deprecated in favor of `Terminal.move_xy(x, y)`. Also, compoundable attributes like `superscript`, `subscript`, `shadow`, and `dim` with colors (e.g., `term.blue_subscript('a')`) are deprecated as they are rarely supported by terminals.
  Fix: Use `term.move_xy(x, y)` for explicit cursor positioning. For text styles like subscript/superscript, consider using Unicode characters or 256/24-bit color codes directly if supported by the terminal, rather than relying on deprecated compound attributes.
• gotcha The `Terminal.location()` context manager cannot be nested. Entering a new `location` context while another is active may lead to unexpected cursor behavior.
  Fix: Ensure that `with term.location(...)` blocks are not nested. Complete one `location` context before entering another.
• gotcha Blessed automatically omits terminal styling sequences if output is redirected to a non-terminal (e.g., a file or pipe). This is a feature, but can be a gotcha if styling is expected in piped output.
  Fix: If you explicitly require styling even when output is redirected, initialize the `Terminal` with `force_styling=True`, e.g., `term = Terminal(force_styling=True)`.
• gotcha Earlier versions of Blessed had less robust Windows support, particularly concerning `async_inkey()`, mouse events, and resize notifications. `async_inkey()` raised `NotImplementedError` on Windows prior to 1.33, and general performance for keyboard input was much slower.
  Fix: For optimal Windows compatibility and performance, ensure you are using Blessed version 1.34 or newer. These versions include significant improvements for console responsiveness and feature support on Windows.
• gotcha Fixes for Kitty keyboard protocol (correct key identification for CSI, alphanumeric keys, etc.) were applied in versions 1.30 and 1.36. Users of Kitty terminal emulators on older Blessed versions might experience incorrect key detection.
  Fix: If using a Kitty terminal and experiencing issues with key input, upgrade Blessed to version 1.36 or higher to benefit from improved protocol detection and key name synthesis.
• breaking Blessed relies on a correctly configured `curses` environment and a functional `terminfo` database. In minimal environments (e.g., Alpine Linux Docker images) or if the `TERM` variable is incorrectly set, `_curses.error: must call (at least) setupterm() first` may occur when performing terminal operations.
  Fix: Ensure that the `terminfo` database is available in your environment (e.g., by installing `ncurses-terminfo` or `ncurses-base` packages on Linux distributions, or their equivalents). Verify that the `TERM` environment variable is set to a supported terminal type (e.g., `xterm`, `screen`, `tmux-256color`).

Install

• pip install blessed Install stable version

Imports

• Terminal

  from blessed import Terminal

  The `Terminal` class is the primary entry point for all Blessed functionality.

Quickstart

This example initializes the terminal, clears the screen, centers a styled message, waits for a single key press using a context manager for `cbreak` mode and a hidden cursor, then prints the pressed key before exiting. The `timeout` for `inkey` uses an environment variable fallback for robustness.

from blessed import Terminal
import os

term = Terminal()
print(term.home + term.clear + term.move_y(term.height // 2))
print(term.black_on_darkkhaki(term.center('press any key to continue.')))

with term.cbreak(), term.hidden_cursor():
    # Use os.environ.get for auth keys in real applications if needed
    inp = term.inkey(timeout=os.environ.get('BLESSED_INKEY_TIMEOUT', 3))

print(term.move_down(2) + 'You pressed ' + term.bold(repr(inp)))
print(term.normal + 'Exiting.')