Installation

FrankenTUI is distributed as a Cargo workspace. There is no standalone installer (yet), so installation is either “clone the source” or “add it as a workspace dependency.” This page covers all three paths and the prerequisites they share.

The audience for this page is anyone who hasn’t yet run cargo run -p ftui-demo-showcase. If you’ve already built the workspace, skip to quick run or project setup.

Expect installation to take under a minute once you have a nightly Rust toolchain installed. The first build takes a few minutes; subsequent builds are incremental.

Prerequisites

FrankenTUI requires nightly Rust, pinned via rust-toolchain.toml. If your terminal shows errors like the option '-Z' is only accepted on the nightly compiler, you are on stable — install nightly and let the toolchain file select it.

Install rustup

If you don’t already have it:

install rustup


curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Install a nightly toolchain

install nightly


rustup toolchain install nightly
rustup component add rust-src --toolchain nightly

The workspace’s rust-toolchain.toml selects nightly automatically when you build inside the checkout, so you don’t need to run rustup default.

(Optional) install supporting tools

For full verification, snapshot blessing, and the doctor_frankentui stack:

optional tools


cargo install cargo-insta       # snapshot test review
cargo install cargo-llvm-cov    # coverage gate
# `jq` and `rg` via your system package manager

Install paths

git clone

The normal path for contributors and anyone running the demo showcase.

git clone


git clone https://github.com/Dicklesworthstone/frankentui.git
cd frankentui
cargo build --release

Then run the showcase:

first run


cargo run -p ftui-demo-showcase

See quick run for demo-view selection and the full env-var reference.

curl tarball

Useful if you want a pinned snapshot of main without git history.

curl tarball


curl -fsSL https://codeload.github.com/Dicklesworthstone/frankentui/tar.gz/main | tar -xz
cd frankentui-main
cargo build --release
cargo run -p ftui-demo-showcase

This is the installer story we’d eventually wire behind a curl | sh script. For now, the tarball + Cargo is the fastest path.

workspace dep

If you already have your own Rust project and want to consume FrankenTUI as a library, add it as a workspace path dependency:

Cargo.toml


[dependencies]
ftui = { path = "../frankentui/crates/ftui" }

This pulls in the public facade crate, which re-exports the pieces you most commonly need. For finer control, depend on the individual crates:

Cargo.toml


[dependencies]
ftui-core    = { path = "../frankentui/crates/ftui-core" }
ftui-runtime = { path = "../frankentui/crates/ftui-runtime" }
ftui-render  = { path = "../frankentui/crates/ftui-render" }
ftui-widgets = { path = "../frankentui/crates/ftui-widgets" }

See project setup for feature flags and the recommended Cargo.toml layout.

crates.io (partial)

Currently available on crates.io:

ftui-core
ftui-layout
ftui-i18n

The remaining 17 crates are in the publish queue (render, runtime, widgets, and the rest). Until those land, prefer workspace path dependencies for the full stack.

Cargo.toml — partial crates.io


[dependencies]
ftui-core = "0.3"     # published
ftui-layout = "0.3"   # published
# remaining crates: use path dependencies

Verify your install

verify


# Build the whole workspace (a few minutes first time)
cargo check --workspace --all-targets
 
# Run the demo showcase
cargo run -p ftui-demo-showcase

You should see the demo showcase’s main menu in your terminal. If you see the option '-Z' is only accepted on the nightly compiler, you are on stable — re-check the nightly toolchain install above.

Troubleshooting

Terminal corrupted after a panic. FrankenTUI uses RAII cleanup via TerminalSession. If you see a broken terminal, make sure you are not force-killing the process. Run reset to recover, and file a bug if you can reproduce.

No mouse events. Mouse reporting must be enabled both in the session (default in the showcase) and in your terminal emulator. Set FTUI_HARNESS_ENABLE_MOUSE=true if running the harness and check that your terminal isn’t intercepting mouse events.

Output flickers on a multiplexer. Inline mode uses DEC 2026 synchronized output where supported. Very old terminals or tmux builds without sync-output support will fall back to overlay redraw. Update your multiplexer, or accept the reduced capability.

Where next

Run the 46-screen showcase and pick a view.

Quick run

A 40-line minimal app walked through.

Hello, tick

Cargo.toml patterns and feature flags.

Project setup

How inline mode coexists with log output.

Embedding in a CLI