asciimatics: cross-platform text UIs and ASCII animation in Python

The gap asciimatics fills between raw curses and a full TUI framework

Python ships with curses in the standard library on Unix-like systems, but the module is absent on Windows and the API is low level: you position the cursor, write characters, and refresh. asciimatics exists to put one cross-platform class in front of that. The README describes it as "a single cross-platform Python class to do all the low-level console function you could ask for", covering coloured and styled text, cursor positioning, non-blocking keyboard input, mouse input where the terminal permits it, console resize handling and screen scraping. The target audience is Python developers building interactive terminal programs: forms, dashboards, and the kind of ASCII animation that the samples directory demonstrates. The README frames the motivation partly as nostalgia ("It brings a little joy to anyone who was programming in the 80s") and partly as a practical abstraction over platform differences. The practical part is the real argument. If you write against Screen, the README claims the same code runs on Windows, OSX and Linux, and it lists CentOS 6 and 7, Raspbian, Ubuntu 14.04, Windows 7, 8 and 10, OSX 10.11 and Android Marshmallow via Termux as verified platforms. Those are old version numbers, which tells you something about when that list was last refreshed, but the abstraction itself is the reason to look at the package.

Screen, Scene and Effect: the three layers you actually program against

The architecture has a clear hierarchy. At the bottom is Screen, which owns the terminal: it knows width, height and colours, and it exposes print_at, get_key and refresh. Everything else is built on top of it. Above Screen sits Scene, which groups a list of Effects and plays them on a Screen for a given number of frames. Effects are the animated units: the README names Cycle, Stars and others, and the package also provides sprites, particle systems and banners. Renderers sit alongside Effects and turn input into text: FigletText converts a string into large ASCII lettering using a pyfiglet font, and the README also mentions image-to-ASCII conversion for JPEG and GIF. The data flow for an animation is therefore: a Renderer produces text, an Effect draws that text onto the Screen at a computed position for each frame, a Scene sequences the Effects, and Screen.wrapper drives the whole loop and restores the terminal when the function returns. For a text UI the flow is different but sits on the same base: widgets such as buttons, text boxes and radio buttons are drawn onto a Frame, which is itself rendered through the Screen. The samples/forms.py and samples/contact_list.py files in the repository are the concrete demonstrations of that second path. The important design consequence is that widgets and animations share one rendering and input layer, so you can mix a form and an animated background in the same application without two competing terminal libraries.

Installing asciimatics and running your first animation

The README gives one install command. It requires Python 3, and the pyproject.toml sets requires-python to >= 3.8. The last version supporting Python 2 was v1.14, so if you are on Python 2 you are pinned to that release and outside the current line.

pip install asciimatics

That command pulls the dependencies for you. According to pyproject.toml those are pyfiglet >= 0.7.2, Pillow >= 2.7.0 and wcwidth >= 0.5.0, plus pywin32 >= 1.0 on Windows only. The README adds that Windows users who are not using pip need to install pywin32 manually. If pip fails to install the dependencies, the README points at requirements.txt in the repository as the fallback list.

The smallest useful program is the low-level hello world from the README. It creates a Screen through the wrapper, prints coloured text at random positions, and exits when you press Q or q.

from random import randint
from asciimatics.screen import Screen

def demo(screen):
    while True:
        screen.print_at('Hello world!',
                        randint(0, screen.width), randint(0, screen.height),
                        colour=randint(0, screen.colours - 1),
                        bg=randint(0, screen.colours - 1))
        ev = screen.get_key()
        if ev in (ord('Q'), ord('q')):
            return
        screen.refresh()

Screen.wrapper(demo)

What you should see is scattered coloured "Hello world!" text that stops when you press Q. Note the shape of the API: Screen.wrapper takes a callable, calls it with the Screen, and handles terminal setup and teardown around it. Nothing in the README suggests you should construct a Screen yourself for normal use.

The second example moves up a layer and is the shortest path to something that looks like a demo rather than a test. It composes two FigletText cycles and a star field into a single Scene.

from asciimatics.effects import Cycle, Stars
from asciimatics.renderers import FigletText
from asciimatics.scene import Scene
from asciimatics.screen import Screen

def demo(screen):
    effects = [
        Cycle(screen, FigletText("ASCIIMATICS", font='big'), int(screen.height / 2 - 8)),
        Cycle(screen, FigletText("ROCKS!", font='big'), int(screen.height / 2 + 3)),
        Stars(screen, 200)
    ]
    screen.play([Scene(effects, 500)])

Screen.wrapper(demo)

The 500 is the frame count for the Scene, so the animation ends on its own. The README links an asciinema recording of this example. Beyond that, the samples directory is the real tutorial: the README says to download the sample files and run them directly with python, and points at a wiki gallery with recordings. The documentation site at asciimatics.readthedocs.org is where the full API reference lives.

Where asciimatics stops being the right tool

The dependency list is the first constraint. Pillow is required even if you never touch image-to-ASCII conversion, because it is a hard dependency in pyproject.toml rather than an extra. Pillow is a large native library, and on constrained targets such as embedded Linux or a minimal container it is the piece most likely to cause build trouble. pywin32 is Windows-only, which is fine, but it means the Windows install path has an extra moving part that the Unix path does not.

Terminal capability is the second constraint, and it is inherent rather than a defect. The README says mouse input works "terminal permitting" and that the package should work on any platform providing a working curses implementation. That word "should" is doing real work. If your target is a CI log, a pipe, or a terminal without proper curses support, the Screen abstraction has nothing to talk to. The README's own platform list includes Windows 7, 8 and 10 and OSX 10.11, which are not current operating systems, so treat the list as evidence that the abstraction has worked historically rather than as a compatibility guarantee for what you are running now.

Release cadence is the third. The newest release is 1.15.0 from 2023-10-25, preceded by 1.14.0 in 2022 and 1.13.0 in 2021. The repository itself was pushed on 2026-07-04, so work continues, but if your process requires regular tagged releases with changelogs you will be consuming master rather than PyPI. That is a different risk profile from a library that ships quarterly, and it is worth deciding which one you are signing up for before you build a product on top. Finally, if all you need is coloured output in a script, asciimatics is the wrong size of tool: an ANSI escape sequence and print will do, without pulling in Pillow.

asciimatics compared with Pytermgui and Textual-style approaches

The related searches around asciimatics include Pytermgui, which is a fair comparison point because both target Python terminal interfaces but from different directions. asciimatics grew out of a curses wrapper and kept that model: you get a Screen, you draw onto it, and the higher-level widgets and effects are conveniences layered on the same immediate-mode rendering. Its layout model is manual. You compute positions, you pass coordinates to print_at or to a widget, and the README's examples show exactly that, with expressions like int(screen.height / 2 - 8) deciding where text lands. That gives you precise control over an animation and makes pixel-level positioning of ASCII art straightforward.

The newer generation of Python TUI libraries takes the opposite approach: a retained widget tree, declarative layout, and styling expressed as markup or CSS-like rules rather than coordinates. That is better when your interface is mostly forms, tables and panes that need to reflow when the terminal resizes, and worse when you are writing a frame-by-frame animation where you want to place a sprite at an exact column. asciimatics sits closer to the animation end of that spectrum, and its own sample set reflects it: fire, fireworks, kaleidoscope, julia, pacman, colour globe. The samples/forms.py and samples/contact_list.py files show the form side is not an afterthought, but the coordinate-based model is still the default mental model. If your project is a data-entry application with a dozen fields, a declarative layout library will save you arithmetic. If your project is an animation or a dashboard where exact placement matters, asciimatics' model is a better match.

Licence, maintenance and what an upgrade actually costs

asciimatics is licensed under the Apache Software Foundation License 2.0, stated in the README and set as the license field in pyproject.toml, with LICENSE listed as the licence file. Apache-2.0 is a permissive licence that includes an express patent grant, which matters if you are embedding the library in a commercial product; it also carries attribution and notice obligations that you should route through your own legal review rather than treat as settled here. The practical implication for a dependency decision is that there is no copyleft obligation on your own code.

On maintenance: the last push to the repository was on 2026-07-04, and the most recent release is 1.15.0 from 2023-10-25. Those two dates together describe a project where the repository sees activity but tagged releases are infrequent. Plan your upgrade path accordingly. The README pins the Python 2 boundary at v1.14, and pyproject.toml requires Python 3.8 or later, so a Python 2 codebase cannot move forward at all. For the Python 3 line, the dependency floor is the thing to watch: pyfiglet >= 0.7.2, Pillow >= 2.7.0 and wcwidth >= 0.5.0 are minimums, not pins, so a fresh install resolves to whatever the current versions are. If you need reproducible builds you should pin them yourself in your own lockfile rather than relying on the package's ranges. There is no migration guide in the README for moving between major versions, and CHANGES.rst is the file to read before upgrading.

Editorial conclusion

Adopt asciimatics if you are writing a Python 3 terminal tool that needs colour, cursor control, keyboard and mouse input, resize handling and ready-made widgets, and you are willing to work against a codebase whose last push was on 2026-07-04 and whose newest release, 1.15.0, dates from 2023-10-25. Do not adopt it if you need a release-per-quarter cadence, if you cannot ship Pillow or pywin32, or if you only need to print coloured text and a plain ANSI escape string would do. Verify first that your target terminal reports the colour depth you expect, that your Python version is at least 3.8, and that your packaging pipeline can build the Pillow and pyfiglet dependencies on every platform you ship to.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. peterbrittain/asciimatics on GitHub
4. README
5. Releases