Ratatui: building terminal user interfaces in Rust

The problem Ratatui solves for Rust CLI authors

Writing a terminal program that redraws a dashboard is mostly bookkeeping. You need to know the terminal size, position every character, handle key events, and put the terminal back the way you found it when the program exits. Ratatui exists to take that bookkeeping off your hands. The README describes it as "a Rust crate for cooking up terminal user interfaces (TUIs)" that "provides a simple and flexible way to create text-based user interfaces in the terminal", aimed at command-line applications, dashboards and other interactive console programs.

The audience is Rust developers who have already decided their interface belongs in a terminal. That is a narrower group than it sounds. A tool that prints one line of output and exits does not need Ratatui. A tool that watches a build, tails logs across panes, or shows a table that updates in place does. The repository topics list cli, rust, terminal, terminal-user-interface, tui and widgets, which matches that scope exactly.

The project was forked from the tui-rs crate in 2023, and the README credits Florian Dehau as the original author of tui-rs. That fork history matters when you are choosing a dependency: Ratatui is a continuation of an existing API lineage, not a greenfield design, and the BREAKING-CHANGES.md file at the repository root exists because that lineage keeps moving.

How Ratatui is put together: core, widgets, backends

The workspace layout is the clearest statement of the architecture. The root Cargo.toml lists members including ratatui, ratatui-core, ratatui-crossterm, ratatui-macros, ratatui-termina, ratatui-termion, ratatui-termwiz and ratatui-widgets, plus examples/apps/*, examples/concepts/* and xtask. The umbrella ratatui crate is version 0.30.2 in the workspace dependency table; ratatui-core and ratatui-crossterm are at 0.1.2, ratatui-macros at 0.7.2, and ratatui-widgets released 0.3.2. Those numbers do not move together, which tells you the split is real rather than cosmetic.

Functionally, ratatui-core holds the drawing model and the terminal abstraction; ratatui-widgets holds the widgets; the ratatui-* backend crates each adapt a terminal library (crossterm, termina, termion, termwiz). The README links ARCHITECTURE.md, which it says "explains the crate organization and modular workspace structure". That is the document to read before you decide which crates to depend on directly.

The programming model is immediate mode. In the quickstart example, run() loops forever, calling terminal.draw(render) on each pass and then blocking on event::read(). render() receives a Frame and calls frame.render_widget("hello world", frame.area()). Nothing is retained between frames: the widget is a value, the frame is a buffer, and the next loop iteration draws again from scratch. If you have used a retained UI toolkit, the inversion is the thing to internalise. There is no widget object to mutate and no tree to reconcile, which is why the same code path handles a static label and a scrolling list.

Installing Ratatui and getting a first app on screen

The README's quickstart has two steps and both go through cargo-generate. The first installs the generator, pinned with --locked so the tool's own dependency resolution is fixed.

cargo install --locked cargo-generate

The second command pulls the template repository. The README shows it without arguments; the surrounding prose says you select a template afterwards, and that choosing the Hello World template produces the application shown in the README.

cargo generate ratatui/templates

What you get is a small binary whose main() installs color_eyre, calls ratatui::init() to take over the terminal, runs the loop, and then calls ratatui::restore(). The run function draws and waits for a key event:

fn run(mut terminal: DefaultTerminal) -> Result<()> {
    loop {
        terminal.draw(render)?;
        if matches!(event::read()?, Event::Key(_)) {
            break Ok(());
        }
    }
}

On screen you should see the text "hello world" filling the frame area, and pressing any key should exit and hand the terminal back. Note the order in main: ratatui::restore() is called after run returns, and the result is propagated afterwards. If you restructure that, keep restore on the exit path, because it is what undoes ratatui::init().

For the widgets and the more involved applications, the README points at two example directories in the repository: Widget Examples under ratatui-widgets/examples and App Examples under examples. The repository also carries examples/concepts, examples/apps and examples/vhs, the last being recorded terminal sessions. Because the examples are workspace members, they build with the rest of the workspace rather than against a published crate.

Where Ratatui is the wrong choice

The immediate-mode loop is the design and also the constraint. Every frame redraws from the widget values you construct in that pass, so any state the user should see between frames lives in your program, not in the library. A form with twenty fields, cursor position, validation state and focus order is your data structure to define and thread through render(). Ratatui gives you the drawing primitives and the event stream, not a component model.

The README is explicit that alternatives exist and names two. Cursive is described as "a ncurses-based TUI library", and iocraft as "a declarative TUI library". That is the honest framing: if you want to declare a UI and let the library manage the tree, Ratatui is not that, and the README does not pretend otherwise.

The second constraint is terminal support. The workspace splits backends into separate crates for crossterm, termina, termion and termwiz, and the root Cargo.toml comments out ratatui-termion from default-members with the note "this is not included as it doesn't compile on windows". Backend choice is therefore a portability decision, not a preference. The README does not document what happens on terminals that lack the capabilities a given backend assumes; that question is left to the backend crates.

The third is version drift inside the workspace. ratatui 0.30.2, ratatui-core 0.1.2 and ratatui-widgets 0.3.2 are released under separate version numbers, and the repository keeps a BREAKING-CHANGES.md alongside the CHANGELOG. If you depend on the sub-crates directly rather than the umbrella crate, a minor bump in one of them can require code changes even when the others are unchanged.

Ratatui compared with Cursive and iocraft

The README's Alternatives section is short and gives the difference in approach in a phrase each. Cursive is ncurses-based, which means it sits on top of the C ncurses library and inherits its model of a screen with a stack of views. iocraft is declarative, so you describe the interface and the library handles the rest.

Ratatui takes neither route. It is pure Rust, with no ncurses dependency in the workspace, and its drawing is immediate rather than declarative. The practical consequence is that Ratatui gives you more control over exactly what lands in the buffer and less structure to lean on. A view stack in Cursive and a component tree in iocraft both encode relationships between screens; in Ratatui you write the code that decides which widget to render on this pass.

If your background is a web framework, the declarative model will feel closer to what you expect, and iocraft is the README's named answer for that. If you are porting something that already assumes ncurses, Cursive is the named answer. Ratatui's own pitch is breadth of widgets and a backend abstraction, and the ecosystem page it links, awesome-ratatui, is where the project points for what has been built with it.

Maintenance, releases and the MIT licence

The repository is not archived and the last push was on 2026-09-19, two days before this was written. The most recent releases are ratatui-v0.30.2, ratatui-widgets-v0.3.2 and ratatui-termwiz-v0.1.2, all published on 2026-06-19. The project runs a release-plz.toml configuration and generates its changelog with git-cliff from Conventional Commits, both named in the README, so release notes are produced from commit messages rather than written by hand.

Upgrade cost is concentrated in two files the repository maintains for exactly that purpose: CHANGELOG.md for what changed, and BREAKING-CHANGES.md for what will require edits. The workspace pins edition 2024 and rust-version 1.88.0, so the minimum toolchain is a hard floor you can check before adopting. The CI workflow at .github/workflows/ci.yml is the gate the project runs on its own code.

Ratatui is MIT licensed. The workspace package section sets license = "MIT" for the crates, and the README closes with a link to the MIT License. MIT is permissive and imposes no copyleft obligation on your application, but it also comes with no patent grant, which some organisations care about. That is a general property of the licence text, not a statement about this project's intentions, and it is the kind of thing to run past whoever handles licensing where you work rather than decide from a README.

Editorial conclusion

Adopt Ratatui if you are writing a Rust CLI or dashboard that needs immediate-mode drawing, a widget set you can compose, and a backend you can swap. Do not adopt it if you want a declarative component tree or a retained widget hierarchy: the README points iocraft and Cursive at that space. Before committing, read BREAKING-CHANGES.md and confirm the crate versions you depend on, because the workspace splits the library into ratatui-core, ratatui-widgets and per-backend crates that version independently.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. ratatui/ratatui on GitHub
4. README
5. Releases