Rio Terminal: a wgpu-based terminal emulator for desktop and the browser

What Rio is, and the problem it targets

Rio is a terminal emulator that renders its grid through the GPU instead of the CPU. The repository describes it as "a modern terminal built to run everywhere," and the topic list backs that up with wgpu, Vulkan and Metal, plus a separate librio-wasm member in the workspace. The practical problem it addresses is the one every terminal user hits eventually: a terminal that redraws text on the CPU starts to show tearing or lag when a full-screen TUI repaints quickly, or when a build log scrolls past faster than the renderer can composite it. Pushing the grid to the GPU is the standard answer, and Rio is one of the projects that takes it.

The audience is narrower than "everyone who uses a terminal." Rio is for people who are comfortable building from source, who care about which graphics backend their terminal uses, and who want a terminal whose rendering layer is a library they could reuse. The workspace layout makes that explicit: sugarloaf handles rendering, rio-vt handles the terminal escape-sequence state machine, rio-grid holds the cell grid, rio-fonts and rio-unicode handle text, and frontends/rioterm is the desktop application that ties them together. If you only want a terminal that works and never think about it again, that decomposition buys you nothing.

How the workspace splits rendering from the terminal state machine

The Cargo.toml workspace lists sixteen members, and the dependency graph is the interesting part. teletypewriter, rio-backend, rio-window, rio-notifier, rio-grapheme-width, sugarloaf, corcovado, rio-graphics, rio-fonts, rio-vt, rio-grid and rio-unicode are all declared as path dependencies at the same version, 0.5.28, which means a release bumps every crate together. Nothing here is published as an independent, separately versioned library.

That has a consequence worth naming. The terminal emulation logic lives in rio-vt, and the rendering lives in sugarloaf; the desktop frontend is a thin consumer of both. The wasm frontend, librio-wasm, consumes the same core. So the data flow is: bytes from the pty enter rio-vt, which produces grid state in rio-grid, which sugarloaf turns into GPU draw calls through rio-window and rio-graphics. Corcovado appears in the member list as well. Whether corcovado is the pty or process layer is not stated in the README, and the README does not document the internal architecture at all, so treat the crate names as the evidence and the docs site as the place to confirm.

The dependency list also tells you something about the performance posture: parking_lot with hardware-lock-elision, rustc-hash, smallvec, and simdutf are all workspace dependencies. Those are choices made by someone optimizing hot paths, not someone reaching for the most portable option.

Installing Rio and running it for the first time

The README points to rioterm.com/docs/install for installation and shows a Repology packaging badge, so the documented path is a distribution package or a build from source rather than a single canonical installer command. The README does not list package manager commands itself, so check the Repology entry for rio-terminal to see whether your platform is covered.

If you build from source, the Makefile gives the entry point. The run target is the plain one:

cargo run -p rioterm --release

That compiles the rioterm frontend in release mode and launches it. The workspace's rust-version is 1.96.1, and rust-toolchain.toml pins the toolchain, so a mismatched rustup default will fail before anything renders.

For a debug build with logging, the Makefile sets an environment variable rather than passing a flag:

RIO_LOG_LEVEL=debug cargo run -p rioterm --no-default-features --features=wayland

There are matching dev-debug-x11 and dev-debug-wayland targets, which tells you the graphics backend is selected at compile time through features rather than at runtime. If you are on Linux and unsure which session you are in, that choice is made for you before the binary exists.

The Makefile also documents a macOS-specific environment variable for the Metal HUD, MTL_HUD_ENABLED, used in the dev targets. That is a development aid, not something you set for daily use.

For the browser target, the Makefile builds the wasm library and then runs a separate frontend package:

cargo build -p rioterm --target wasm32-unknown-unknown --lib
cargo run -p rioterm-wasm

Note that this references a package named rioterm-wasm, while the workspace member is librio-wasm. Both names appear in the repository and the README does not reconcile them, so confirm which package actually exists in your checkout before relying on that second command.

Where Rio is the wrong tool

The README is short, and what it omits matters more than what it says. There is no documented rollback procedure, no compatibility statement about which config keys changed between 0.5.26 and 0.5.28, and no migration note for anyone upgrading across those releases. Three releases landed in under a month: v0.5.26 on 2026-08-23, v0.5.27 on 2026-08-30, and v0.5.28 on 2026-09-17. A version series that moves that fast on the 0.5 line is not making stability promises, and the README does not claim otherwise.

If your terminal config is a file you sync across a fleet of machines and expect to keep working untouched for a year, that release cadence is a liability rather than a feature. The same applies if you need a terminal with a documented plugin or extension API, because nothing in the README or the workspace layout suggests one exists.

The compile-time backend selection is a second limitation. Because wayland and x11 are separate features rather than a runtime choice, a single binary built for one does not fall back to the other. On a machine that boots into either session depending on how you logged in, that is a real constraint, and the README does not describe a runtime override.

Finally, the browser story is the least documented part. The README's headline claim is that Rio runs "everywhere," but the only browser-related evidence is the librio-wasm member and the two Makefile lines. There is no README section explaining what the browser build can and cannot do relative to the desktop one.

Rio against Ghostty and WezTerm

The two comparisons people search for are Ghostty and WezTerm, and the difference in approach is visible in the repository structure rather than in any benchmark. Rio's distinguishing choice is that the rendering layer is its own crate, sugarloaf, sitting alongside libsugarloaf, and the workspace also carries librio and librio-wasm as embeddable entry points. That is an architecture aimed at reuse: the terminal core is meant to be consumed by more than one frontend, and the wasm target is the proof of concept.

WezTerm is also written in Rust and also GPU-accelerated, but it is a single large application with a Lua configuration system, so its extension surface is scripting inside the terminal rather than a crate you link against. Ghostty takes a different route again, targeting native platform rendering with Zig and a config file format of its own. If what you want is a terminal you configure heavily in Lua, Rio is not that. If what you want is a rendering crate you can pull into another Rust project, Rio is structured for it and the others are not.

None of this is a performance claim. No benchmark numbers for any of the three appear in the README, and the repository publishes none.

Maintenance, licence and the upgrade bill

The repository is not archived, and the last push was on 2026-09-20, so this is a project with current commits. Releases ship often: three in the four weeks before that push. That cadence is the main cost of adoption, because the workspace versions every crate in lockstep at 0.5.28, so a release is a whole-workspace event rather than a patch to one component.

Rio is MIT licensed, which is permissive and imposes no copyleft obligation on downstream users. The workspace Cargo.toml declares license = "MIT" for the workspace package, and the repository carries a LICENSE file at the top level. That covers Rio's own code. It says nothing about the licences of the third-party crates in the dependency tree, and the truncated Cargo.toml shows only part of that list, so a licence audit of a shipped binary is still your job. This is not legal advice.

Upgrade cost has a specific shape here. Because the frontend, the VT layer and the renderer version together, you cannot hold sugarloaf at one version while moving the frontend forward. If you vendor any of these crates, expect to move them as a set.

Editorial conclusion

Adopt Rio if you want a GPU-rendered terminal whose rendering layer is a separate, reusable crate and you are willing to track a project that publishes releases frequently, with v0.5.28 on 2026-09-17. Do not adopt it if you need a stable config schema you can copy between machines without checking the changelog, or if your platform is not in the packaging index. Before committing, verify that your distribution has a package, confirm the 1.96.1 MSRV against your toolchain, and read the config page at rioterm.com/docs/config for the keys your current terminal relies on.

Frequently asked questions

Official sources

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