Textual Development Tools

1.8.0 · active · verified Tue Apr 14

textual-dev is a Python library that provides command-line utilities and a development console to aid in building and debugging Textual TUI applications. It is released alongside the main Textual framework, which typically has a rapid release cadence, often weekly or bi-weekly for minor versions. The current version is 1.8.0.

Warnings

breaking The `textual[dev]` extra was refactored into a separate `textual-dev` package in Textual v0.29.0. Users upgrading from older Textual versions (prior to 0.29.0) must now explicitly install `textual-dev` in addition to `textual` to access the development tools.
Fix: `pip install textual textual-dev`
gotcha Textual, the core framework, has a rapid development cycle with frequent releases (often weekly or bi-weekly). While `textual-dev` aims to maintain compatibility, breaking changes in Textual's API can occasionally affect the functionality of the dev tools. Always check Textual's changelog for significant updates.
Fix: Refer to the Textual documentation and changelog for compatibility notes before upgrading major/minor versions of either `textual` or `textual-dev`.
gotcha While the `textual console` can display output from `print()` statements in your application, the recommended approach for logging and debugging in Textual is to use `app.log()` or the dedicated logging facilities provided by the `textual` framework. `print()` is generally discouraged for structured debugging output in Textual apps.
Fix: Replace `print()` calls with `self.log("Your message")` or `self.app.log("Your message")` within your Textual application classes. Configure Textual's logging for more control.
gotcha Recent releases of `textual-dev` (v1.8.0) explicitly add Python 3.14 compatibility. If you are using an older version of `textual-dev` or `textual` with Python 3.14, you may encounter unexpected issues or lack of support.
Fix: Upgrade to `textual-dev` 1.8.0 or later for Python 3.14 compatibility: `pip install --upgrade textual-dev`.

Install

pip install textual-dev Install textual-dev
pip install textual textual-dev Install Textual (framework) and dev tools

Quickstart

To use textual-dev, first save the provided Python code as `my_app.py`. Then, open *two separate terminal windows*. In the first terminal, start the Textual development console. In the second, run your application in development mode, enabling it to connect to the console. This setup allows you to see logs, debug information, and perform live editing tasks. Terminal 1: ```bash pip install textual textual-dev textual console ``` Terminal 2: ```bash python my_app.py --dev # or, if textual is installed in path: # textual run --dev my_app.py ```

import os
from textual.app import App, ComposeResult
from textual.widgets import Header, Footer, Static

# --- Save this as my_app.py ---
class MyApp(App):
    BINDINGS = [("d", "toggle_dark", "Toggle dark mode")]

    def compose(self) -> ComposeResult:
        yield Header()
        yield Static("Hello, Textual Devtools!", id="hello")
        yield Footer()

    def action_toggle_dark(self) -> None:
        self.dark = not self.dark

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

view raw JSON →