Install & Compatibility
Where this runs
tested against v2.12.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.95 runs
installs and imports cleanly · install 0.0s · import 4.222s · 160.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 19.0s · import 3.614s · 158MB
153MB installed
● package 153MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
cl
✓ import chainlit as cl
cl.on_chat_start
✓ @cl.on_chat_start
Decorator for functions that run when a new chat session begins.
cl.on_message
✓ @cl.on_message
Decorator for functions that handle incoming user messages.
cl.Message
✓ await cl.Message(content='Hello!').send()
✗ cl.Message(content='Hello!').send()
Chainlit is async-first; all `cl.Message` operations must be `await`ed to send the message and avoid returning a coroutine object.
This quickstart demonstrates a basic Chainlit application. Create a file named `app.py`, paste the code, and run it using `chainlit run app.py -w` in your terminal. This will start the Chainlit UI in your browser, where you can interact with the bot. The `@cl.on_chat_start` function sends a welcome message, and `@cl.on_message` handles incoming user messages, simulating an intermediate step and then echoing the user's input.
import chainlit as cl
import os
# Optional: Set CHAINLIT_AUTH_SECRET if authentication is enabled for your app
# os.environ['CHAINLIT_AUTH_SECRET'] = os.environ.get('CHAINLIT_AUTH_SECRET', 'your_secret_key_here_for_testing')
@cl.on_chat_start
async def start():
await cl.Message(
content="Welcome! I am a simple Chainlit bot. Type anything to get a response."
).send()
@cl.on_message
async def main(message: cl.Message):
# Simulate a tool's response
await cl.Message(author="Tool", content=f"Processing: {message.content}", indent=1).send()
# Send back the final answer
await cl.Message(content=f"You said: {message.content}").send()
# To run this:
# 1. Save the code as `app.py`
# 2. Run `chainlit run app.py -w` in your terminal
chainlit --version
Debug
Known issues
breakingChainlit v2.9.4 introduced a breaking change requiring a database migration for users employing persistence. You must run `ALTER TABLE steps ADD COLUMN IF NOT EXISTS modes JSONB;` to migrate your database.fixExecute the SQL command `ALTER TABLE steps ADD COLUMN IF NOT EXISTS modes JSONB;` on your Chainlit database before upgrading or starting applications on version 2.9.4 or higher.
affects: >=2.9.4
gotchaChainlit is an async-first framework. All operations that interact with the UI, such as `cl.Message().send()` or other `cl` methods that involve sending data, must be `await`ed. Failing to do so will result in a coroutine object being returned instead of the expected action, potentially leading to silent failures or unexpected behavior.fixAlways prepend `await` to asynchronous Chainlit function calls, e.g., `await cl.Message(...).send()`.
affects: All versions
gotchaWhen authentication is enabled (e.g., via `CHAINLIT_AUTH_SECRET` or OAuth), 'Invalid authentication token' errors can occur, especially when rendering images. This often indicates a missing or incorrect `CHAINLIT_AUTH_SECRET` environment variable.fixEnsure the `CHAINLIT_AUTH_SECRET` environment variable is correctly set and accessible to your Chainlit application. For OAuth, verify all `OAUTH_PROVIDER_CLIENT_ID`, `OAUTH_PROVIDER_CLIENT_SECRET`, and domain variables are correctly configured.
affects: All versions with authentication enabled
gotchaConfiguration defined in `chainlit.toml` (e.g., project name, UI settings) may occasionally be ignored, particularly in certain older versions (e.g., v2.7.2). This can lead to default settings being applied instead of your custom configurations.fixVerify your `chainlit.toml` file is correctly formatted and located. If issues persist, ensure `load_dotenv()` (if used) is called before `import chainlit`. Consider updating to the latest Chainlit version, as such issues are often addressed.
affects: <2.9.4 (and potentially other versions)
Errors
Common errors & fixes
'chainlit' is not recognized as an internal or external command, operable program or batch file
The Chainlit command-line executable is not located in a directory listed in your system's PATH environment variable after installation.
fixAdd the Python `Scripts` directory (e.g., `C:\Users\YOUR_USERNAME\AppData\Local\Programs\Python\PythonXX\Scripts` on Windows or your virtual environment's `bin` directory) to your system's PATH. Alternatively, execute Chainlit commands using `python -m chainlit run app.py`.
AttributeError: module 'chainlit' has no attribute 'langchain_factory'
Chainlit removed the `langchain_factory`, `llama_index_factory`, and `langflow_factory` functions in newer versions to simplify its API, making older code incompatible.
fixUpdate your application code to use `@cl.on_chat_start` to initialize your LangChain or LlamaIndex agent/chain and store it in `cl.user_session`, then retrieve it in `@cl.on_message` for message processing.
WebSocket Connection Error / Unable to connect to server
This issue commonly arises in deployment environments (e.g., Docker, Gunicorn with multiple workers, or behind a reverse proxy/load balancer) due to misconfigured WebSocket support, lack of sticky sessions, or Cross-Origin Resource Sharing (CORS) policies blocking the connection.
fixEnsure your deployment environment supports WebSockets. For Gunicorn with multiple workers, enable sticky sessions on your load balancer or add `transports = ['websocket']` to your `.chainlit/config.toml`. When running in Docker, use `--host 0.0.0.0` with `chainlit run`. For CORS, configure `allow_origins` in your `.chainlit/config.toml` to include your frontend's origin.
ModuleNotFoundError: No module named 'langchain.callbacks'
This error occurs when using Chainlit's `LangchainCallbackHandler` with LangChain `v1.x.x` because LangChain significantly refactored its module structure, changing the paths for its callback components.
fixUpgrade Chainlit to a version officially compatible with LangChain `v1.x.x`. If a compatible Chainlit version is not available, you may need to manually update import statements for LangChain callbacks or refer to Chainlit's documentation for the correct way to integrate with the new LangChain API.
pydantic.errors.PydanticUserError: CodeSettings is not fully defined
This indicates a Pydantic version incompatibility, where Chainlit or one of its dependencies (like LangChain or LlamaIndex) expects a different Pydantic API than the one installed.
fixPin your Pydantic version to one that is known to be compatible with your installed Chainlit and other integrated library versions, for example, by adding `pydantic==2.10.1` or `pydantic<2` to your `requirements.txt` and reinstalling dependencies.
Upgrade
Version history
2.12.0latest on PyPI · released Aug 25, 2026
Audit
Dependencies
pythonrequiredChainlit requires Python 3.10 or higher, but less than 4.0.0.