Chainlit: a Python framework for chat UIs on top of LLM backends

The problem Chainlit solves for Python LLM developers

A language model backend is usually a script: an async function that takes a prompt, calls a provider, and returns text. Turning that script into something a non-engineer can open in a browser normally means writing a frontend, a websocket layer, and a session store. Chainlit takes the position that the Python file is the application. You decorate a function with @cl.on_message, and the framework supplies the browser UI, the transport and the message rendering.

The audience is narrow and specific. If your logic already lives in Python and you want a chat surface for it, the framework removes the frontend work. If your logic lives in JavaScript, or if your product is a document Q&A widget embedded in a marketing site, Chainlit is the wrong layer. The README's own description is "Build python production-ready conversational AI applications in minutes, not weeks", and the Python qualifier is doing real work in that sentence.

How the decorator model and the step trace work

Chainlit is a monorepo. The repository root holds backend/, frontend/, libs/, docs/ and scripts/, with a pnpm workspace for the TypeScript side and a uv workspace whose only member is backend. The Python package you install is the backend; the browser UI is a separate frontend build that the package serves.

The programming model is decorator-driven. @cl.on_message registers the handler invoked on each user input, and @cl.step(type="tool") marks a function as a discrete step in the run. Steps are the part worth understanding: when you await a step function, Chainlit emits an intermediate event to the UI before the final message arrives, so the user sees that a tool is running rather than a frozen input box. The README example uses cl.sleep(2) as a fake tool and then sends the result with cl.Message(content=tool_res).send(). The cl namespace is the whole API surface for this pattern: decorators for lifecycle, Message for output, step for intermediate work.

Because the handlers are async, the natural integration point is any async Python client. Nothing in the README ties the framework to a specific provider, which is why the cookbook lists OpenAI, Anthropic, LangChain, LlamaIndex, ChromaDB and Pinecone among its examples.

Installing Chainlit and running a first app

Installation is a single pip command, and the README pairs it with a self-check command. Run both from a terminal:

pip install chainlit
chainlit hello

If a browser opens with the hello app, the install is sound. That second command is the fastest way to separate a packaging problem from a code problem, because it exercises the server and the frontend without any of your own code.

For the development version, the README gives a GitHub install that builds the frontend from source and therefore requires Node and pnpm on the system:

pip install git+https://github.com/Chainlit/chainlit.git#subdirectory=backend/

For a first real app, create demo.py. The README's example defines a tool step and a message handler:

import chainlit as cl


@cl.step(type="tool")
async def tool():
    await cl.sleep(2)
    return "Response from the tool!"


@cl.on_message
async def main(message: cl.Message):
    tool_res = await tool()
    await cl.Message(content=tool_res).send()

Run it with the -w flag so the process reloads when you edit the file:

chainlit run demo.py -w

Type anything into the input box. You should see a step appear, pause for roughly two seconds, and then a message containing the tool's return string. The two-second pause is the point of the example: it is long enough to show what a slow tool call looks like in the UI.

Where Chainlit stops being the right tool

The framework assumes a conversational, turn-based interaction. If your product is a data table with filters, a multi-page form, or a dashboard of charts, you are fighting the model rather than using it, and a general Python UI framework will cost you less effort.

The larger caveat is governance, and the README states it plainly. Chainlit is community-maintained: as of May 1st 2025 the original team stepped back from active development, and the project is maintained by @Chainlit/chainlit-maintainers under a formal Maintainer Agreement. The same notice says Chainlit SAS provides no warranties on future updates. That is an unusual thing to find in a README, and it is the single most important line for anyone evaluating the project for production. It does not mean the code is abandoned: the last push to main was on 2026-09-09, and version 2.12.0 was released on 2026-08-25. It does mean there is no commercial entity standing behind a support commitment, so your risk assessment has to rest on the maintainer group and on your own ability to read the source.

A second limitation is architectural rather than organisational. The README does not describe persistence for chat history, and the data layer is only referenced in the related documentation, not in the README body. If you need durable conversation storage, treat that as an integration you must design and verify yourself rather than something the quickstart gives you.

Chainlit compared with Streamlit

The comparison people reach for is Chainlit versus Streamlit, and the difference is in the execution model rather than the feature list. Streamlit reruns the whole script top to bottom on every interaction; state is carried in a session object and widgets drive the rerun. That model fits dashboards and data apps, where the page is a function of the current inputs.

Chainlit inverts this. A handler registered with @cl.on_message is invoked for that message, and the step mechanism emits events as the handler progresses. The unit of work is a run with a trace, not a page render. That is why the tool step in the quickstart can appear in the UI before the final answer: the framework has a concept of intermediate output, which a rerun-based model does not.

The practical consequence is that porting a Streamlit app to Chainlit is not a rewrite of widgets but a rewrite of control flow. If your app is genuinely conversational and long-running, Chainlit's model matches it better. If your app is a form that produces a chart, Streamlit's model matches it better.

Licence, release process and upgrade cost

Chainlit is licensed under Apache-2.0, and the LICENSE file sits at the repository root. Apache-2.0 is permissive and includes an explicit patent grant, which matters if you are embedding the framework in a commercial product. The repository also carries a PRIVACY_POLICY.md and a SECURITY.md, so there is a stated channel for vulnerability reports. None of this is legal advice; if the patent grant or the notice requirements affect your distribution, that is a question for your own counsel.

On upgrades, the release history shows an uneven cadence: 2.11.0 on 2026-04-07, 2.11.1 on 2026-04-22, then a four-month gap to 2.12.0 on 2026-08-25. That pattern is consistent with a volunteer maintainer group rather than a scheduled release train, and it means you should not plan around predictable minor releases. The repository root contains both CHANGELOG.md and RELENG.md; RELENG.md is the file that describes how releases are made, so read it before you decide how tightly to pin your dependency. Pinning to an exact version is the low-effort hedge here, because the frontend and backend ship together and a mismatch between them is the failure mode you would rather avoid.

Editorial conclusion

Adopt Chainlit if you want a Python-first chat surface for an LLM backend and you are comfortable with a community-maintained project: the last push to main was on 2026-09-09 and release 2.12.0 shipped on 2026-08-25. Skip it if you need a general dashboarding tool or a vendor-backed support contract, since Chainlit SAS states it provides no warranties on future updates. Before committing, read RELENG.md and CHANGELOG.md to see how releases are cut, and check the data layer docs if you need persistence beyond the default in-memory session.

Frequently asked questions

Official sources

1. Chainlit/chainlit on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases