Guide · Open source

How to use Textual: build terminal and browser apps in Python

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Textual is an open-source Python framework for building interactive user interfaces. You write the interface in Python, and the same app can run in a terminal window or be served to a web browser. This guide shows you how to install it, run a sample app, understand the basic structure of a Textual program, and share an app with textual serve.

TextualTextualize/textual · ★ 37.6k · MIT Install options & downloads

Quick start

1Install Python. Make sure Python is installed on your machine, since Textual is a Python package.
2Install Textual. Run pip install textual textual-dev in your terminal.
3Run the demo. Run python -m textual to see sample widgets and features.
4Create a Python file. Save the clock example or your own App subclass in a .py file.
5Run your app. Start the file with python so the app opens in your terminal.
6Debug with the dev console. Use the textual-dev dev console from a second terminal to see logs and print output.
7Serve in a browser. Run textual serve with your app command to share it through a web browser.

What you need before you install Textual

Textual is installed as a Python package, so the main prerequisite is Python. Apps are built by writing Python code, so this guide assumes you are comfortable running Python scripts.

The project's README lists macOS, Linux and Windows in its OS support badge.

Python installed on your machine
Comfort with writing and running a Python file
A terminal to run your app in

Install Textual with pip

Install Textual with pip. The README installs the textual-dev package at the same time, which provides the developer console and other helpful tools.

See the project's getting started guide for more detail.

pip install textual textual-dev

Run the built-in demo

Once installed, you can run a short demo to see what Textual can do. The README also mentions a separate textual-demo project, which you can try without installing it by using uv.

python -m textual

Write your first app: a clock

The README's example is a small app that shows the current time. It defines an App subclass with CSS for layout, a compose method that yields a Digits widget, and an on_ready method that starts a timer with set_interval to update the clock every second.

Save the code in a Python file and run it with python. The app starts when the file is executed because of the if __name__ == "__main__" block.

App subclass: the root of your Textual application
CSS string: sets layout, such as centering the screen
compose(): yields the widgets that make up the interface
set_interval(1, ...): calls a method once per second
query_one(Digits): finds the widget so its content can be updated

from datetime import datetime

from textual.app import App, ComposeResult
from textual.widgets import Digits


class ClockApp(App):
    CSS = """
    Screen { align: center middle; }
    Digits { width: auto; }
    """

    def compose(self) -> ComposeResult:
        yield Digits("")

    def on_ready(self) -> None:
        self.update_clock()
        self.set_interval(1, self.update_clock)

    def update_clock(self) -> None:
        clock = datetime.now().time()
        self.query_one(Digits).update(f"{clock:%T}")


if __name__ == "__main__":
    app = ClockApp()
    app.run()

Use widgets, layouts and themes

Textual's widget library includes buttons, tree controls, data tables, inputs, text areas and more. You combine widgets with its layout system to build the interface you need. Predefined themes are included so apps look reasonable without much styling work.

The command palette opens with ctrl+p and supports fuzzy search. You can add your own commands to it.

Buttons, data tables, inputs, text areas, list views and tree controls
A flexible layout system
Predefined themes
Fuzzy-search command palette opened with ctrl+p

Debug with the dev console

Running an app in the terminal makes print output hard to see. The textual-dev package supplies a dev console that connects to your application from a second terminal. Logged messages, print statements, system messages and events appear there.

Serve your app in a web browser

Any Textual app can be served to a browser with the textual serve command. The README's example serves the demo app. Textual Web is a separate option mentioned in the README for serving apps.

textual serve "python -m textual"

What people use it for

Building a terminal clock or status display that updates over time
Creating internal tools or dashboards that run over SSH or in a terminal
Sharing a terminal app in the browser with textual serve
Building forms and data tables for command-line workflows

Frequently asked questions

What is Textual used for?

Textual is a Python framework for building interactive user interfaces. Apps can run in a terminal window or be served to a web browser. It is suited to text-based apps and dashboards.

Is Textual free?

Textual is released under the MIT licence, according to the project's listing. Check the licence file in the repository for the full terms.

What do I need to run Textual?

The README lists Python as the prerequisite. You install Textual with pip, using pip install textual textual-dev.

Does Textual work on Windows, macOS and Linux?

The project's OS support badge lists macOS, Linux and Windows. The README does not describe other platforms.

Can I use Textual to build a desktop or mobile app?

No. The README describes terminal and browser targets only, so Textual is not a fit for native desktop or mobile GUIs.

How does Textual compare to Rich or urwid?

Rich, urwid, Prompt Toolkit and Blessed are listed as comparable projects. Textual provides a full widget set, layout system and themes for building apps; check each project's docs to decide which fits your needs.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Textual suits Python developers who want terminal apps with buttons, tables, forms and optional browser sharing, including internal tools run over SSH. It is not a good choice for non-programmers, for native desktop or mobile GUIs, or for projects that need a language other than Python.

Install options & downloads