Registry / web-framework / textual-serve

textual-serve

library1.1.3pypypi✓ verified 23d ago

textual-serve is an open-source project that allows you to serve and access your Textual TUI (Text-based User Interface) applications via a web browser. The Textual app runs on a machine/server under your control and communicates with the browser via a custom protocol over WebSockets. End-users interacting with the app via their browser do not have direct access to the machine the application is running on, only to the running Textual app. It effectively turns Textual TUIs into multi-user web applications. The current version is 1.1.3, and it has a regular release cadence with recent updates.

web-framework http-networking communication

pip install textual-serve

github ↗package ↗

INSTALL

IMPORT

SIG · TEXTUAL-SERVE

textual-serve

web-frameworkpythonv1.1.3

Install

6.1s avg

Import

813ms

Disk

50MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.1.3 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.856s · 48.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 6.1s · import 0.770s · 51MB

50MB installed

● package 50MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Server

✓ from textual_serve.server import Server

✗ from textual_serve import Server

The `Server` class is nested within the `server` module inside `textual_serve`.

This quickstart demonstrates how to create a simple Textual application and then serve it using `textual-serve`. The `Server` class takes a shell command to launch your Textual app. The app will be accessible in a web browser, typically at `http://localhost:8000` by default.

from textual.app import App, ComposeResult from textual.widgets import Header, Footer, Static from textual_serve.server import Server class MinimalApp(App): BINDINGS = [("q", "quit", "Quit")] def compose(self) -> ComposeResult: yield Header() yield Static("Hello from Textual Served!") yield Footer() def action_quit(self) -> None: self.exit() # Save the above Textual app as 'my_app.py' # Then run the textual-serve server programmatically: # Note: This will block and serve the app on http://localhost:8000 # You can also use the command line: textual serve my_app.py if __name__ == "__main__": # To run a Textual app directly: # app = MinimalApp() # app.run() # To serve it via textual-serve print("Starting textual-serve on http://localhost:8000...") print("Press Ctrl+C to stop the server.") server = Server("python my_app.py", host="localhost", port=8000) server.serve()

textual-serve --version

Debug

Known issues

gotchaPasting text into Textual inputs via Ctrl+V (or equivalent) in a web browser served by `textual-serve` may not work as expected if the text was copied from outside the GUI. This is a known issue.

fix

Users may need to right-click and use the browser's paste option, or manually type the input. Check GitHub issues for potential workarounds or fixes.

affects: All versions

breaking`textual-serve` relies heavily on the `textual` framework. `textual` underwent significant changes and breaking API updates frequently in its pre-1.0 versions. While `textual-serve` itself is past 1.0, ensure compatibility with the `textual` version you are using, as updates to `textual` might indirectly affect `textual-serve` applications.

fix

Always check the release notes for both `textual` and `textual-serve` before upgrading. Pin `textual` dependency versions if stability is critical.

affects: Prior to textual-serve v1.0.0 (indirectly via textual library updates)

gotchaThe `Server` class expects a shell command that successfully launches a Textual application. If the command is incorrect or the Textual app fails to start, `textual-serve` will encounter a `RuntimeError` or similar issues.

fix

Thoroughly test the shell command (`python your_app.py` or `textual run your_app.py`) independently in a terminal to ensure it works before passing it to `textual_serve.server.Server`.

affects: All versions

gotchaIt's crucial to understand that `textual-serve` does not expose a raw shell in the browser. Instead, it communicates with the running Textual application via a custom WebSocket protocol. This is a security feature, but it means users cannot execute arbitrary commands on the host system.

fix

Design Textual applications served with `textual-serve` with this isolated execution model in mind. Any host system interaction must be explicitly built into the Textual app's functionality.

affects: All versions

Errors

Common errors & fixes

textual serve command not found

The `textual serve` command-line tool is not installed or its executable script is not in your system's PATH.

fix

Ensure `textual-serve` is installed via `pip install textual-serve` and that your Python environment's script directory is in your system's PATH. Alternatively, you can run it using `python -m textual_serve serve`.

ModuleNotFoundError: No module named 'textual_serve'

The `textual-serve` Python package is not installed in the currently active Python environment.

fix

Install the package using pip: `pip install textual-serve`.

Address already in use

The default port (8000) or a specified port that `textual serve` is trying to use is already occupied by another application.

fix

Stop the process currently using the port, or specify a different port for textual-serve using `textual serve --port <new_port>` (e.g., `textual serve --port 8001`).

WebSocket connection to 'ws://...' failed:

The web browser failed to establish a WebSocket connection to the `textual-serve` server, often due to the server not running, an incorrect server address/port, firewall restrictions, or proxy issues.

fix

Verify that `textual serve` is actively running, confirm the server URL and port match what the browser is trying to connect to, check for any firewall rules blocking the port, and ensure proxy configurations correctly handle WebSockets if applicable.

Upgrade

Version history

1.1.3latest on PyPI · released Nov 1, 2025

Audit

Dependencies

textualrequiredtextual-serve is designed to serve Textual applications, making Textual a core dependency for any functional use.

Agent activity

30 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/Textualize/textual-serve ↗

packagehttps://pypi.org/project/textual-serve/ ↗