Asciimatics

1.15.0 verified Mon Apr 27 auth: no python

A cross-platform package to replace curses (mouse/keyboard input & text colours/positioning) and create ASCII animations. Current version 1.15.0, requires Python >= 3.8. Releases are semi-regular, roughly every 6-12 months.

pip install asciimatics

Common errors

error AttributeError: module 'asciimatics' has no attribute 'Screen' ↓

cause Incorrect import path: `from asciimatics import Screen`.

fix

Use from asciimatics.screen import Screen.

error ModuleNotFoundError: No module named 'asciimatics.screen' ↓

cause Old version of asciimatics (<1.13.0) where widgets were not yet a subpackage, OR missing parentheses in import with Python 3.

fix

Update to latest version: pip install --upgrade asciimatics.

error TypeError: __init__() missing 1 required positional argument: 'screen' ↓

cause Custom Effect not passing screen to parent class. Since 1.9.0, screen is mandatory for Effect.

fix

Ensure custom Effect __init__ calls super().__init__(screen, *args, **kwargs) and passes screen parameter.

error Termux: 'os' has no attribute 'kill' / screen_width not found ↓

cause Asciimatics does not fully support Android/Termux without extra terminal emulation.

fix

Use a different terminal or run on desktop OS (Linux, macOS, Windows).

Warnings

breaking Asciimatics 1.15.0 drops Python 2 and requires Python >= 3.8. Python 3.9+ recommended. ↓

fix Upgrade to Python 3.8+ and asciimatics 1.15.0+.

breaking In 1.14.0, Frame borders and scroll bars changed: Frame now supports scroll bars without borders. To have no border and no scroll bar, use Frame(has_border=False, can_scroll=False) explicitly. ↓

fix If you used Frame with has_border=False and expected no scroll bar, add can_scroll=False.

breaking In 1.9.0, screen became a mandatory positional parameter for all Effect constructors. Custom effects must pass screen to parent class. ↓

fix Update custom Effect __init__ to accept and pass screen parameter.

deprecated The old top-level import `from asciimatics import Screen` is deprecated since 1.13.0. Use `from asciimatics.screen import Screen`. ↓

fix Update imports as per correct paths above.

gotcha When using threads, Screen is not thread-safe. Do not call screen methods from multiple threads. ↓

fix Use Screen.wrapper() or manage screen access from a single thread.

gotcha On Windows, asciimatics may not handle mouse events without the pynput library. Install pynput or use keyboard only. ↓

fix pip install pynput for mouse support on Windows.

Imports

Screen

wrong

from asciimatics import Screen

correct

from asciimatics.screen import Screen

Screen is in the screen subpackage, not at top level

Frame

wrong

from asciimatics import Frame

correct

from asciimatics.widgets import Frame

Frame is in widgets subpackage since 1.13.0

Scene

wrong

from asciimatics import Scene

correct

from asciimatics.scene import Scene

Scene is in the scene subpackage

Effect

wrong

from asciimatics import Effect

correct

from asciimatics.effects import Effect, ...

Effects are in the effects subpackage

Sprite

wrong

from asciimatics import Sprite

correct

from asciimatics.sprites import Sprite

Sprites are in the sprites subpackage

Label, Button, Text, Layout

wrong

from asciimatics import Label

correct

from asciimatics.widgets import Label, Button, Text, Layout

All widgets are in the widgets subpackage since 1.13.0

Quickstart

Simple hello world using FigletText. Run with Python; creates a full-screen animation.

# Demo: bouncing ball animation
import os
from asciimatics.screen import Screen
from asciimatics.scene import Scene
from asciimatics.effects import Effect
from asciimatics.renderers import FigletText

def demo(screen):
    renderer = FigletText("Hello")
    effects = [
        Effect(screen, 0, 0, renderer, delete=False)
    ]
    scene = Scene(effects, -1, name="Hello")
    screen.play([scene], stop_on_resize=True)

Screen.wrapper(demo)