Getting started
All you need to get started building Textual apps.
Requirements
Textual requires Python 3.7 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
You can install Textual via PyPI.
If you plan on developing Textual apps, then you should install textual[dev]
. The [dev]
part installs a few extra dependencies for development.
pip install "textual[dev]"
If you only plan on running Textual apps, then you can drop the [dev]
part:
Demo
Once you have Textual installed, run the following to get an impression of what it can do:
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)
▏
CTRL+C Quit CTRL+B Sidebar CTRL+T Toggle Dark mode CTRL+S Screenshot F1 Notes
Examples
The Textual repository comes with a number of example apps. To try out the examples, first clone the Textual repository:
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 ../
Textual CLI
If you installed the dev dependencies you have access to the textual
CLI command. There are a number of sub-commands which will aid you in building Textual apps.
See devtools for more about the textual
command.
Need help?
See the help page for how to get help with Textual, or to report bugs.