Textualize/textual · critical · RuntimeError

Unable to import {driver_import!r}; {driver_class!r} is not

Error message

Unable to import {driver_import!r}; {driver_class!r} is not a Driver class 

What it means

RuntimeError raised in App.get_driver_class when TEXTUAL driver_import resolves to something that is not a Driver subclass. The driver is specified via the TEXTUAL environment variable as 'module:Class'.

Source

Thrown at src/textual/app.py:1595

        building a Textual app.

        Returns:
            A Driver class which manages input and display.
        """

        driver_class: Type[Driver]

        driver_import = constants.DRIVER
        if driver_import is not None:
            # The driver class is set from the environment
            # Syntax should be foo.bar.baz:MyDriver
            module_import, _, driver_symbol = driver_import.partition(":")
            driver_module = importlib.import_module(module_import)
            driver_class = getattr(driver_module, driver_symbol)
            if not inspect.isclass(driver_class) or not issubclass(
                driver_class, Driver
            ):
                raise RuntimeError(
                    f"Unable to import {driver_import!r}; {driver_class!r} is not a Driver class "
                )
            return driver_class

        if WINDOWS:
            from textual.drivers.windows_driver import WindowsDriver

            driver_class = WindowsDriver
        else:
            from textual.drivers.linux_driver import LinuxDriver

            driver_class = LinuxDriver
        return driver_class

    def __rich_repr__(self) -> rich.repr.Result:
        yield "title", self.title
        yield "id", self.id, None
        if self.name:

View on GitHub (pinned to 06dbeef4bb)

Solutions

1. Ensure the class subclasses Driver (from textual.driver import Driver) and is exported at module level
2. Fix the env format: export TEXTUAL="my_package.drivers:MyDriver"
3. Unset TEXTUAL to use the auto-selected platform driver

Example fix

# before
# TEXTUAL="my_driver:create" (factory function)
class MyDriver:
    ...

# after
from textual.driver import Driver
class MyDriver(Driver):
    ...
# TEXTUAL="my_driver:MyDriver"

import importlib, inspect
from textual.driver import Driver
mod, _, sym = driver_import.partition(':')
cls = getattr(importlib.import_module(mod), sym)
assert inspect.isclass(cls) and issubclass(cls, Driver)

def is_driver_class(cls) -> bool:
    import inspect
    from textual.driver import Driver
    return inspect.isclass(cls) and issubclass(cls, Driver)

When it happens

Trigger: Setting TEXTUAL="my_module:MyDriver" where MyDriver is a function or unrelated class; typo in module path; driver class not subclassing textual.driver.Driver.

Common situations: Custom driver development, CI environments injecting TEXTUAL, or stale env vars pointing at moved code.

Related errors

• Can't animate attribute {attribute!r} on {obj!r}; attribute
• Don't know how to animate {value!r}; Can only animate <int>,
• Can't encode {datum!r}
• must be bytes
• More data expected

AI-assisted analysis of Textualize/textual@06dbeef4bb (2026-08-27). Data as JSON: /api/errors/9302f9d75c44e14c. Report an issue: GitHub.