{"id":26733,"library":"asciimatics","title":"Asciimatics","description":"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.","status":"active","version":"1.15.0","language":"python","source_language":"en","source_url":"https://github.com/peterbrittain/asciimatics","tags":["console","curses","terminal","animation","tui"],"install":[{"cmd":"pip install asciimatics","lang":"bash","label":"Install from PyPI"}],"dependencies":[{"reason":"Image conversion and sprite loading","package":"Pillow","optional":true},{"reason":"Mouse handling on some platforms (optional)","package":"pynput","optional":true},{"reason":"Windows console API (optional, Windows only)","package":"winitAPI","optional":true}],"imports":[{"note":"Screen is in the screen subpackage, not at top level","wrong":"from asciimatics import Screen","symbol":"Screen","correct":"from asciimatics.screen import Screen"},{"note":"Frame is in widgets subpackage since 1.13.0","wrong":"from asciimatics import Frame","symbol":"Frame","correct":"from asciimatics.widgets import Frame"},{"note":"Scene is in the scene subpackage","wrong":"from asciimatics import Scene","symbol":"Scene","correct":"from asciimatics.scene import Scene"},{"note":"Effects are in the effects subpackage","wrong":"from asciimatics import Effect","symbol":"Effect","correct":"from asciimatics.effects import Effect, ..."},{"note":"Sprites are in the sprites subpackage","wrong":"from asciimatics import Sprite","symbol":"Sprite","correct":"from asciimatics.sprites import Sprite"},{"note":"All widgets are in the widgets subpackage since 1.13.0","wrong":"from asciimatics import Label","symbol":"Label, Button, Text, Layout","correct":"from asciimatics.widgets import Label, Button, Text, Layout"}],"quickstart":{"code":"# Demo: bouncing ball animation\nimport os\nfrom asciimatics.screen import Screen\nfrom asciimatics.scene import Scene\nfrom asciimatics.effects import Effect\nfrom asciimatics.renderers import FigletText\n\ndef demo(screen):\n    renderer = FigletText(\"Hello\")\n    effects = [\n        Effect(screen, 0, 0, renderer, delete=False)\n    ]\n    scene = Scene(effects, -1, name=\"Hello\")\n    screen.play([scene], stop_on_resize=True)\n\nScreen.wrapper(demo)\n","lang":"python","description":"Simple hello world using FigletText. Run with Python; creates a full-screen animation."},"warnings":[{"fix":"Upgrade to Python 3.8+ and asciimatics 1.15.0+.","message":"Asciimatics 1.15.0 drops Python 2 and requires Python >= 3.8. Python 3.9+ recommended.","severity":"breaking","affected_versions":"<1.15.0"},{"fix":"If you used Frame with has_border=False and expected no scroll bar, add can_scroll=False.","message":"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.","severity":"breaking","affected_versions":">=1.14.0"},{"fix":"Update custom Effect __init__ to accept and pass screen parameter.","message":"In 1.9.0, screen became a mandatory positional parameter for all Effect constructors. Custom effects must pass screen to parent class.","severity":"breaking","affected_versions":">=1.9.0"},{"fix":"Update imports as per correct paths above.","message":"The old top-level import `from asciimatics import Screen` is deprecated since 1.13.0. Use `from asciimatics.screen import Screen`.","severity":"deprecated","affected_versions":">=1.13.0"},{"fix":"Use Screen.wrapper() or manage screen access from a single thread.","message":"When using threads, Screen is not thread-safe. Do not call screen methods from multiple threads.","severity":"gotcha","affected_versions":"*"},{"fix":"pip install pynput for mouse support on Windows.","message":"On Windows, asciimatics may not handle mouse events without the pynput library. Install pynput or use keyboard only.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Use `from asciimatics.screen import Screen`.","cause":"Incorrect import path: `from asciimatics import Screen`.","error":"AttributeError: module 'asciimatics' has no attribute 'Screen'"},{"fix":"Update to latest version: pip install --upgrade asciimatics.","cause":"Old version of asciimatics (<1.13.0) where widgets were not yet a subpackage, OR missing parentheses in import with Python 3.","error":"ModuleNotFoundError: No module named 'asciimatics.screen'"},{"fix":"Ensure custom Effect __init__ calls super().__init__(screen, *args, **kwargs) and passes screen parameter.","cause":"Custom Effect not passing screen to parent class. Since 1.9.0, screen is mandatory for Effect.","error":"TypeError: __init__() missing 1 required positional argument: 'screen'"},{"fix":"Use a different terminal or run on desktop OS (Linux, macOS, Windows).","cause":"Asciimatics does not fully support Android/Termux without extra terminal emulation.","error":"Termux: 'os' has no attribute 'kill' / screen_width not found"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}