1. Project Overview & Quickstart (Textualize/textual)
File: README.md
Textual
Build cross-platform user interfaces with a simple Python API. Run your apps in the terminal or a web browser.
Textual's API combines modern Python with the best of developments from the web world, for a lean app development experience.
De-coupled components and an advanced testing framework ensure you can maintain your app for the long-term.
Want some more examples? See the examples directory.
"""
An App to show the current time.
"""
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()[!TIP]
Textual is an asynchronous framework under the hood. Which means you can integrate your apps with async libraries — if you want to.
If you don't want or need to use async, Textual won't force it on you.
Widgets
Textual's library of widgets covers everything from buttons, tree controls, data tables, inputs, text areas, and more…
Combined with a flexible layout system, you can realize any User Interface you need.
Predefined themes ensure your apps will look good out of the box.
Installing
Install Textual via pip:
pip install textual textual-devSee getting started for details.
Demo
Run the following command to see a little of what Textual can do:
python -m textualOr try the textual demo without installing (requires uv):
uvx --python 3.12 textual-demoDev Console
How do you debug an app in the terminal that is also running in the terminal?
The textual-dev package supplies a dev console that connects to your application from another terminal.
In addition to system messages and events, your logged messages and print statements will appear in the dev console.
See the guide for other helpful tools provided by the textual-dev package.
Command Palette
Textual apps have a fuzzy search command palette.
Hit ctrl+p to open the command palette.
It is easy to extend the command palette with custom commands for your application.
Textual ❤️ Web
Textual apps are equally at home in the browser as they are the terminal. Any Textual app may be served with textual serve — so you can share your creations on the web.
Here's how to serve the demo app:
textual serve "python -m textual"In addition to serving your apps locally, you can serve apps with Textual Web.
Textual Web's firewall-busting technology can serve an unlimited number of applications.
Since Textual apps have low system requirements, you can install them anywhere Python also runs. Turning any device into a connected device.
No desktop required!
Join us on Discord
Join the Textual developers and community on our Discord Server.
File: docs/index.md
hide:
- toc
- navigation
!!! tip inline end
See the navigation links in the header or side-bar.
Click :octicons-three-bars-16: (top left) on mobile.Welcome
Welcome to the Textual framework documentation.
Get started{ .md-button .md-button--primary } or go straight to the Tutorial
What is Textual?
Textual is a Rapid Application Development framework for Python, built by Textualize.io.
Build sophisticated user interfaces with a simple Python API. Run your apps in the terminal or a web browser!
:material-clock-fast:{ .lg .middle } :material-language-python:{. lg .middle } Rapid development
Uses your existing Python skills to build beautiful user interfaces.
:material-raspberry-pi:{ .lg .middle } Low requirements
Run Textual on a single board computer if you want to.
:material-microsoft-windows:{ .lg .middle } :material-apple:{ .lg .middle } :fontawesome-brands-linux:{ .lg .middle } Cross platform
Textual runs just about everywhere.
:material-network:{ .lg .middle } Remote
Textual apps can run over SSH.
:fontawesome-solid-terminal:{ .lg .middle } CLI Integration
Textual apps can be launched and run from the command prompt.
:material-scale-balance:{ .lg .middle } Open Source
Textual is licensed under MIT.
Built with Textual
Textual has enabled an ecosystem of applications and tools for developers and non-developers alike.
Here are a few examples.
Toad
Toad is a beautiful terminal front-end for AI coding tools such as OpenHands, Claude Code, Gemini CLI, and many more.
--8<-- "docs/images/screenshots/toad.svg"Posting
The API client that lives in your terminal.
Posting is a beautiful open-source terminal app for developing and testing APIs.
Toolong
A terminal application to view, tail, merge, and search log files (plus JSONL).
--8<-- "docs/images/screenshots/toolong.svg"Memray
Memray is a memory profiler for Python, built by Bloomberg.
--8<-- "docs/images/screenshots/memray.svg"Dolphie
Your single pane of glass for real-time analytics into MySQL/MariaDB & ProxySQL
--8<-- "docs/images/screenshots/dolphie.svg"Harlequin
An easy, fast, and beautiful database client for the terminal.
--8<-- "docs/images/screenshots/harlequin.svg"Examples
The following examples are taken from the examples directory.
Click the tabs to see the code behind the example.
=== "Pride example"
```{.textual path="examples/pride.py"}
```=== "pride.py"
```py
--8<-- "examples/pride.py"
```=== "Calculator example"
```{.textual path="examples/calculator.py" columns=100 lines=41 press="6,.,2,8,3,1,8,5,3,0,7,1,wait:400"}
```=== "calculator.py"
```python
--8<-- "examples/calculator.py"
```=== "calculator.tcss"
```css
--8<-- "examples/calculator.tcss"
```2. Official Technical Reference & Guides (Textualize/website)
File: docs/about-us.md
hide:
- navigation
- toc
About Us
We are a team of developers working from Edinburgh, Scotland; and remote.
The Team
{align=right}
Will McGugan :material-github: :material-twitter: :material-linkedin:
CEO / Founder. Creator of Rich, Textual, PyFilesystem. Author.
{align=right}
Darren Burns :material-github:
Open Source developer. Creator of Ward, Dunk, And Kupo.
{align=right}
Dave Pearson :material-github:
Free software advocate. Polyglot programmer.
{align=right}
Rodrigo Girão Serrão :material-twitter:
Mathematician. Software developer. Educator.
Philosophy
We are strong advocates of Open Source software and embrace building in public. As developers building tools for developers, we know that trust can only built by sharing and contributing within the developer community.
We believe in inclusivity in computing and within our company.
--8<-- "docs/images/pride.svg"
File: docs/index.md
hide:
- navigation
- toc
Textualize.io
!!! tip inline end "Mailing List"
Sign up to our [mailing list](http://eepurl.com/hL0BF1) for occasional news about Textualize.We are building Textual — a Rapid Application Development framework for Python.
As the world's most popular programming language, Python has made a huge impact in a broad range of fields from data science to biology.
At the same time, web development has become more and more specialized, putting it out of reach for the majority of developers. We have a solution for that.
Textual leverages developers existing Python skills and the tools they already know, to build highly functional User Interfaces.
Making it possible for developers of all skill levels to build applications for their company or organisation.
No more slow, expensive out-sourcing.
Apps can be built in-house by a single developer that would previously have taken a team of specialists to build — and in a fraction of the time.
Textual apps run on MacOS, Linux, and Windows. In the terminal, the web, and Jupyter notebooks.
Want to know more?
Read about our plans for Textual, and upcoming web service.
:material-download: :material-file-pdf-box: The case for Textual
:material-download: :material-file-pdf-box: Textualize Cloud Service
Follow our progress on the Textual Blog or visit the Textual Website for more information.
Textual in action
A brief video of some of Textual's capabilities.
File: docs/projects.md
title: "Projects"
hide:
- navigation
- toc
Projects
We are software developers, building software for other developers.
Here you will find the projects we work on.
Textual
Rapid Application Development, powered by Rich.
Expect a lot more from your terminal with this modern API to build interactive applications on par with the Web and Desktop.
!!! info "Coming Soon"
Run Textual apps in the browser as easily as the terminal. Build web apps with just your Python skills.:material-github: Textual{ .md-button .md-button--primary } :fontawesome-brands-discord: Textual{ .md-button .md-button--primary }
Textual screenshots
<li>
<a href="/images/textual-screenshots/cloudtrail.svg" target="blank">
--8<-- "docs/images/textual-screenshots/cloudtrail.svg"
</a>
Visualize Amazon CloudTrail data.
</li>
<li>
<a href="/images/textual-screenshots/datadog.svg" target="blank">
--8<-- "docs/images/textual-screenshots/datadog.svg"
</a>
[DDQA](https://github.com/DataDog/ddqa) (by Datadog) is a tool for users of Jira to perform QA of anticipated releases of code on GitHub.
</li>
<li>
<a href="/images/textual-screenshots/baca.svg" target="blank">
--8<-- "docs/images/textual-screenshots/baca.svg"
</a>
[Baca](https://github.com/wustho/baca) — an Open Source TUI e-book reader.
</li>
<li>
<a href="/images/textual-screenshots/markdown-viewer.svg" target="blank">
--8<-- "docs/images/textual-screenshots/markdown-viewer.svg"
</a>
A remarkably full featured Markdown browser, that runs in your terminal.
</li>
<li>
<a href="/images/textual-screenshots/twobee.svg" target="blank">
--8<-- "docs/images/textual-screenshots/twobee.svg"
</a>
Explore DNA sequences stored in "2 bit" files.
</li>
<li>
<a href="/images/textual-screenshots/mandelbrot.svg" target="blank">
--8<-- "docs/images/textual-screenshots/mandelbrot.svg"
</a>
An experimental mandelbrot set explorer for the terminal.
</li>Rich
Rich for Python
<a href="/images/rich.svg" target="blank">
--8<-- "docs/images/rich.svg"The project which started it all.
In 2020, Will McGugan wrote the first line of Rich, a project which would become one of the most popular in the Python ecosystem, used by over seventy thousand projects.
Rich started out as a simple tool to colorize text, but has since grown in to a sophisticated library for beautiful formatting in terminal.
Rich has over 43,000 GitHub stars and counting, and is used
:material-github: Rich{ .md-button .md-button--primary }
File: docs/why-i-founded-textualize.md
hide:
- navigation
- toc
Why I Founded Textualize
I founded Textualize with the express purpose of reversing what I saw as years of neglect in a critical developer tool: the terminal. That little window and flashing cursor that is the starting point and constant companion for many a software project.
Neglect may be nothing new in the tech world. When we collectively decide that the new generation of software has arrived, we neglect what came before it. It's a natural consequence of progress and no bad thing.
What's different about the terminal is that nobody got the memo that we should stop using it. The browser, with all its power, is seen as a companion to the terminal by developers, not as a rival. Terminals appear to reside in a niche they are so ideally suited for that tech Darwinism can't touch them. In a 2022 survey of developers, 89% responded that they have a terminal open at least half of the day. Clearly developers are as engaged with the terminal as much as the browser, and yet few tech companies give it more than a second thought.
Rich
Rich for Python
<a href="/images/rich.svg" target="_blank">
--8<-- "docs/images/rich.svg"I see the neglect in the terminal world as a mistaken assumption that whatever can be done in the terminal, has been done, and there is little to gain from attempting to enhance the terminal experience. My work on Rich made it clear to me that developers were delighted by any visual enhancements. Not only was innovation still possible with a technology older than most developers, but there was real demand for it.
Terminals and browsers coexist so comfortably in developer's minds because there are distinct use-cases for each; we instinctively know when to reach for one over the other. Yet there is a class of terminal application that defies such an obvious taxonomy. The TUI, or Text User Interface, is an application which takes over the terminal and can present windows, views, and dialogs. There was a time when these apps were the primary way of interacting with a computer. That era is long gone. Yet, like the terminal itself, TUIs survive to this day. In fact, they are more popular than ever.
There are some technical advantages to these apps: a developer can operate a TUI over an encrypted channel on a remote server. But this is often not the primary or even secondary reason why a developer would reach for a TUI over a web application.
TUIs can transition seamlessly from the command line and back again without interrupting the developer's train of thought, which explains some of their popularity. TUIs are also popular for many of the reasons that terminals themselves are popular: a minimal keyboard-focused interface that rewards repeated use. One that is free of distractions and context switching. Additionally, terminals are a natural fit for the clean lines, dark mode, aesthetic that even web apps seek to emulate.
Having talked to many developers on the subject, I understood that there were few use-cases where a developer would not want a TUI. Many enthused about TUI interfaces to system administration tasks, network automation, internal analytics, and crypto currency bots, but for every work related application there was a desire for a productivity tool, calendar, distraction-free writing and any number of apps were developers would eschew the web or desktop in favor of a TUI.
There is clearly demand but short supply. TUIs have traditionally been built with an API conceived in the 90s. There has been almost zero innovation since then. Neglect meant that none of the advancements in the world of application development made it to the terminal.
Textual
My answer to this is Textual, a project I started in 2021 to take the best of innovation from the web and desktop world and bring it to the terminal. The prospect of being able to build TUIs without grappling with archaic tools created a lot of buzz in the Python community and beyond.
The first iteration of Textual was a hobby project, created to pass the time and satisfy some intellectual curiosity. Only once I was satisfied that there were no technical reasons as to why this had never been attempted, did I realize there was opportunity here. The unique characteristics of TUIs, namely low systems requirements, cross platform, remotely accessible, could find a previously unexplored niche -- which only Textual could fully exploit.
I would not want Textual to stray from its roots as Free and Open Source software, but selling "picks and shovels" would not compromise that. The opportunity felt compelling enough for me to quit my job in late 2021 and live on savings for a year. At the end of the year I would have built Textual and a related web service which I could then turn into a business.
Founding Textualize was very much a plan B. But funding enabled me to be more ambitious in my mission to rejuvenate the terminal. Our next challenge as a company is to solve the problem of distribution. Paradoxically, although terminal software is installed on every desktop computer ever shipped, the terminal is little known outside of developers and other technical users. If TUIs are to truly reach their potential we need to make them accessible to more typical users.
I see Textualize as the vanguard in a terminal renaissance. I don't know why there is renewed interest in the terminal as a platform now. We could have asked more of terminals years ago. But we are in a unique position to halt and reverse years of neglect.
** CEO / Founder **