Install & Compatibility
Where this runs
tested against v0.4.0 · 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
muslpy 3.10–3.960 runs
installs and imports cleanly · install 0.0s · import 2.776s · 67.2MB
glibcpy 3.10–3.960 runs
installs and imports cleanly · install 10.0s · import 2.617s · 67MB
68MB installed
● package 68MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Chat
✓ from shinychat.express import Chat
✗ from shiny.ui import Chat
While `ui.Chat` also works if `shiny` is imported, `shinychat.express.Chat` is the direct path for `shinychat`'s primary quickstart. For `shiny.App` structure, `chat = ui.Chat()` is used within the `server` function, with `ui.chat_ui()` in `app_ui`.
This quickstart creates a simple ShinyChat application where the AI assistant acts as an echo bot, repeating whatever the user types. It demonstrates the basic setup of a `Chat` instance, displaying its UI, and handling user input with an asynchronous callback.
import os
from shiny.express import ui
from shinychat.express import Chat
# Set some Shiny page options
ui.page_opts(
title="Hello ShinyChat Echo Bot",
fillable=True,
fillable_mobile=True,
)
# Create a chat instance and display its UI
chat = Chat(id="chat")
chat.ui(
messages=["Hello! I'm an echo bot. Type something and I'll repeat it!"]
)
# Define a callback to run when the user submits a message
@chat.on_user_submit
async def handle_user_input(user_input: str):
# Simply echo the user's input back to them
await chat.append_message(f"You said: {user_input}")
# To run this app, save it as `app.py` and execute:
# `uv shiny run --reload app.py` (if using uv)
# or `python -m shiny run --reload app.py` (if using pip/python)
Errors
Common errors & fixes
ImportError: cannot import name 'ToolResultDisplay' from 'chatlas.types'
`pydantic` is a soft dependency for `shinychat`'s `providers` extra, and is required by `chatlas` types like `ToolResultDisplay`. If `pydantic` is not installed, this error occurs.
fixInstall `pydantic` by running `pip install pydantic` or `pip install shinychat[providers]`.
TypeError: Chat() got an unexpected keyword argument 'messages'
The `messages` parameter in the `Chat` constructor was deprecated in v0.2.0.
fixInitialize `chat = Chat(id="chat")` without the `messages` argument, then pass initial messages to the `chat.ui()` method: `chat.ui(messages=["Your initial message"])`.
ModuleNotFoundError: No module named 'shiny.express' or 'ModuleNotFoundError: No module named 'shiny''
`shinychat` is built on top of `Shiny for Python`. If `shiny` is not installed, any imports from `shiny` or `shinychat.express` will fail.
fixInstall the `shiny` package: `pip install shiny`.
RuntimeError: Python version 3.9 or earlier is not supported by shinychat.
Shinychat v0.2.9 and later require Python 3.10 or newer.
fixUpgrade your Python environment to version 3.10, 3.11, or 3.12.
Upgrade
Version history
0.4.0latest on PyPI · released May 27, 2026
Audit
Dependencies
shinyrequiredShinychat is a UI component for Shiny apps; basic functionality often relies on Shiny's ecosystem.
python>=3.10requiredRequired as of shinychat v0.2.9.
langchain>=1.0.0optionalOptional dependency for integrating with LangChain LLM providers.
chatlasoptionalHighly recommended for interacting with LLM providers, though not strictly required for the basic chat UI.
pydanticoptionalA soft dependency included in the `providers` extra, necessary for certain features (e.g., `chatlas.types.ToolResultDisplay`).
python-dotenvoptionalRecommended for securely loading environment variables like API keys.