Textual TUI workers

February 3, 2026

Notes on the Textual Worker API.

Docs: https://textual.textualize.io/guide/workers

Workers are tasks by default. If the worker’s thread parameter is set to True, the worker will be a thread instead of a task.

Worker events #

When a worker changes state, it sends a Worker.StateChanged event to the widget where the worker was created.

For example (messy):

    @on(Worker.StateChanged)
    def worker_state_change_handler(self, event: Worker.StateChanged) -> None:
        # TODO: handle WorkerState.ERROR and WorkerState.CANCELLED
        worker_name = event.worker.name
        state = event.state
        if worker_name == "launch_processing":
            if state == WorkerState.RUNNING:
                self.query_one("#launch-processing", Button).disabled = True
                self.query_one(FilteredDirectoryTree).disabled = True
            if state == WorkerState.SUCCESS:
                self.query_one("#launch-processing", Button).disabled = False
                self.query_one("#stop-processing").disabled = True
                self.query_one(FilteredDirectoryTree).disabled = False

Note that WorkerState is an enum, with the following values: RUNNING, CANCELLED, ERROR, SUCCESS.

Tags: