Textual Speedups

0.2.1 · active · verified Fri Apr 10

textual-speedups provides optional Rust-based performance enhancements for the Textual TUI framework. It implements core Textual classes like `Offset`, `Size`, `Region`, and `Spacing` in Rust to potentially make Textual applications faster. Currently at version 0.2.1 (released November 28, 2025), the library is experimental and its development follows the Textual ecosystem, with releases occurring a few times a year.

Warnings

gotcha Textual-speedups is currently experimental and should not be used in production environments. It is under active development and may not be stable.
Fix: Use for development and testing purposes only. Monitor the official Textual and textual-speedups repositories for updates on stability and production readiness.
gotcha There is a possibility of encountering edge cases, crashes, or subtle behavioral differences when using textual-speedups due to its experimental nature.
Fix: Thoroughly test your Textual application with textual-speedups enabled. Report any issues to the project's GitHub repository. If unexpected behavior occurs, disable the speedups as a first troubleshooting step.
gotcha For simpler Textual applications, the performance benefits from textual-speedups might not be noticeable. The speedups primarily target internal geometry and layout calculations, which may only significantly impact complex UIs.
Fix: Benchmarking your specific application is recommended to determine if textual-speedups provides a measurable improvement for your use case. Do not expect universal, dramatic speedups across all Textual apps.
gotcha To temporarily or permanently disable textual-speedups, an environment variable must be set. This is useful for debugging or comparing performance with and without the speedups.
Fix: Set the environment variable `TEXTUAL_SPEEDUPS=0` before running your Textual application. Example: `TEXTUAL_SPEEDUPS=0 python -m textual` or `os.environ['TEXTUAL_SPEEDUPS'] = '0'` within Python before app initialization.

Install

pip install textual-speedups Install textual-speedups

Imports

Automatic Integration
```
No direct imports from 'textual_speedups' are typically needed. Once installed, Textual automatically detects and utilizes the Rust speedups.
```
Users continue to import geometry classes (e.g., Offset, Size) directly from the 'textual.geometry' module; 'textual-speedups' transparently replaces their Python implementations with Rust versions.

Quickstart

To use textual-speedups, simply install it into the same Python environment as your Textual application. Textual will automatically detect and integrate the speedups. The example above is a standard Textual clock app; installing textual-speedups would potentially optimize its underlying Textual operations without requiring any code changes to the app itself.

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

# Set TEXTUAL_SPEEDUPS=0 in your environment to disable speedups for comparison:
# os.environ['TEXTUAL_SPEEDUPS'] = '0'

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()
        # The interval timer and widget updates are areas where
        # textual-speedups might offer performance benefits.
        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()

view raw JSON →