Skip to content
Get packs

Guide · Open source

How to use ratatui: set up a Rust terminal UI project

Updated · written with AI from the project's own documentation and checked against our catalogue data

Ratatui is a Rust crate (library) for building terminal user interfaces (TUIs), the text-based screens used in command-line tools, dashboards and interactive console programs. This guide is for developers who already work in Rust and want to start a terminal interface. By the end you will know what you need installed, how to generate a starter project, and where to find the documentation for building your own layouts and widgets.

Ratatuiratatui/ratatui · ★ 23.1k · MIT

Quick start

  1. 1Install prerequisites. Make sure Rust and Cargo are installed on your machine.
  2. 2Install cargo-generate. Run cargo install --locked cargo-generate to get the project generator.
  3. 3Generate a project. Run cargo generate ratatui/templates and select the Hello World template.
  4. 4Run the starter app. Build and run the generated project in your terminal, then press a key to exit.
  5. 5Read the docs. Use docs.rs/ratatui and the Ratatui website to learn layouts and widgets.
  6. 6Build your own screen. Replace the render function with your own layout and widgets.

What you need before you start

Ratatui is a Rust crate, so you need Rust and Cargo installed. The README lists these as the prerequisites for the install method it describes, which uses a package manager.

Ratatui is a library, not a finished application. You write the program yourself, using the library to draw layouts and widgets in the terminal.

  • Rust and Cargo
  • A terminal to run your program in
  • Basic familiarity with Rust

Generate a starter project with the templates

The quickest route is the Ratatui templates. First install cargo-generate, a tool that creates projects from templates. Then run cargo generate against the ratatui/templates repository and select the Hello World template.

The README notes that this template produces a small application that displays 'hello world' and exits when you press a key.

cargo install --locked cargo-generate cargo generate ratatui/templates

Understand the Hello World code

The generated program sets up the terminal with ratatui::init(), runs a loop that draws each frame and waits for a key event, then calls ratatui::restore() before exiting. Error handling uses color_eyre.

The render function receives a Frame and draws the text 'hello world' into the area returned by frame.area(). This draw-then-handle-events loop is the basic pattern you will extend.

  • ratatui::init() prepares the terminal
  • terminal.draw(render) draws one frame
  • event::read() from crossterm waits for input
  • ratatui::restore() returns the terminal to its normal state
fn render(frame: &mut Frame) { frame.render_widget("hello world", frame.area()); }

Find documentation and examples

The official docs on docs.rs cover the full API. The Ratatui website explains core concepts and has step-by-step tutorials. Widget Examples show individual widgets, while App Examples show larger programs.

The README also points to a Ratatui Forum for questions and an EuroRust 2024 talk that covers common concepts and what can be built.

  • API docs: docs.rs/ratatui
  • Website concepts and tutorials: ratatui.rs
  • Widget examples and app examples in the GitHub repository
  • Forum: forum.ratatui.rs

Use Ratatui on small devices (no_std)

Ratatui can run on no_std targets such as microcontrollers, using a backend such as Mousefood. Turning off default features also turns off the layout cache, so the README says to enable it again and size it for your device.

This setup is more advanced. Check the 'Using Ratatui without std' section in the docs before you start.

ratatui = { version = "0.30", default-features = false, features = ["layout-cache"] }

What people use it for

  • Interactive command-line tools with menus and forms
  • Dashboards that show live information in the terminal
  • Console programs that need a text-based interface
  • Small embedded devices via no_std with a backend such as Mousefood

Frequently asked questions

Is ratatui free to use?

Yes. The project is licensed under the MIT License, as stated in the README and the license section of the repository.

What do I need to install ratatui?

You need Rust and Cargo. The README's install method uses cargo-generate, which you install with cargo install --locked cargo-generate, then create a project from the ratatui/templates repository.

Is ratatui a finished application?

No. Ratatui is a Rust library for building terminal user interfaces. The README does not describe a ready-made end-user app, so you write the program yourself.

Can I use ratatui without writing Rust?

Not as described. Ratatui is a Rust crate, so you need to write Rust code to use it.

What is ratatui's relation to tui-rs?

Ratatui was forked from the tui-rs crate in 2023 to continue its development. The README credits Florian Dehau for creating tui-rs.

What are alternatives to ratatui?

The README lists Cursive, an ncurses-based TUI library, and iocraft, a declarative TUI library. Pick based on whether you prefer an ncurses-style API or a declarative one.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use ratatui if you are a Rust developer building an interactive terminal program or dashboard and want a library with documentation and an active community. Pick something else if you need a finished end-user app, a graphical window instead of a terminal, or a non-Rust language; the README lists Cursive and iocraft as alternatives.

Install options & downloads