Skip to content

Getting started

All you need to get started building Textual apps.

Requirements

Textual requires Python 3.8 or later (if you have a choice, pick the most recent Python). Textual runs on Linux, macOS, Windows and probably any OS where Python also runs.

Your platform

Linux (all distros)

All Linux distros come with a terminal emulator that can run Textual apps.

macOS

The default terminal app is limited to 256 colors. We recommend installing a newer terminal such as iterm2, Kitty, or WezTerm.

Windows

The new Windows Terminal runs Textual apps beautifully.

Installation

Here's how to install Textual.

From PyPI

You can install Textual via PyPI, with the following command:

pip install textual

If you plan on developing Textual apps, you should also install textual developer tools:

pip install textual-dev

From conda-forge

Textual is also available on conda-forge. The preferred package manager for conda-forge is currently micromamba:

micromamba install -c conda-forge textual

And for the textual developer tools:

micromamba install -c conda-forge textual-dev

Textual CLI

If you installed the developer tools you should have access to the textual command. There are a number of sub-commands available which will aid you in building Textual apps. Run the following for a list of the available commands:

textual --help

See devtools for more about the textual command.

Demo

Once you have Textual installed, run the following to get an impression of what it can do:

python -m textual

If Textual is installed you should see the following:

Textual Demo ⭘Textual Demo TOP                                        Widgets                                           Textual widgets are powerful interactive components.                                          Widgets   Build your own or use the builtin widgets.                                                     • Input Text / Password input.                                                               Rich content • Button Clickable button with a number of styles.                                            • Switch A switch to toggle between states.                                                 ▃▃  • DataTable A spreadsheet-like widget for navigating data. Cells may contain text or Rich    renderables.                                                                               CSS • Tree An generic tree with expandable nodes.                                                 • DirectoryTree A tree of file and folders.                                                   • ... many more planned ... ▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁ ▎▊ ▎▊▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▎▊ ▎Username▊will▎▊ ▎▊▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▎▊ ▎▊▅▅ ▎▊▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▎▊ ▎Password▊Password▎▊ ▎▊▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▎▊ ▎▊ ▎▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▊ ▎ Login ▊ ▎▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▊ ▎▊ ▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔  Foo                   Bar                   Baz                   Foo                    Cell (0, 0)           Cell (0, 1)           Cell (0, 2)           Cell (0, 3)            Cell (1, 0)           Cell (1, 1)           Cell (1, 2)           Cell (1, 3)            Cell (2, 0)           Cell (2, 1)           Cell (2, 2)           Cell (2, 3)            Cell (3, 0)           Cell (3, 1)           Cell (3, 2)           Cell (3, 3)            Cell (4, 0)           Cell (4, 1)           Cell (4, 2)           Cell (4, 3)            Cell (5, 0)           Cell (5, 1)           Cell (5, 2)           Cell (5, 3)            Cell (6, 0)           Cell (6, 1)           Cell (6, 2)           Cell (6, 3)            Cell (7, 0)           Cell (7, 1)           Cell (7, 2)           Cell (7, 3)            Cell (8, 0)           Cell (8, 1)           Cell (8, 2)           Cell (8, 3)            Cell (9, 0)           Cell (9, 1)           Cell (9, 2)           Cell (9, 3)          ▂▂  Cell (10, 0)          Cell (10, 1)          Cell (10, 2)          Cell (10, 3)           Cell (11, 0)          Cell (11, 1)          Cell (11, 2)          Cell (11, 3)           Cell (12, 0)          Cell (12, 1)          Cell (12, 2)          Cell (12, 3)           Cell (13, 0)          Cell (13, 1)          Cell (13, 2)          Cell (13, 3)          ▏  ^b Sidebar  ^t Toggle Dark mode  ^s Screenshot  f1 Notes  ^q Quit ▏^p palette

Examples

The Textual repository comes with a number of example apps. To try out the examples, first clone the Textual repository:

git clone https://github.com/Textualize/textual.git

git clone git@github.com:Textualize/textual.git

gh repo clone Textualize/textual

With the repository cloned, navigate to the /examples/ directory where you will find a number of Python files you can run from the command line:

cd textual/examples/
python code_browser.py ../

Widget examples

In addition to the example apps, you can also find the code listings used to generate the screenshots in these docs in the docs/examples directory.

Need help?

See the help page for how to get help with Textual, or to report bugs.