About libghostty-vt
Important
This book is an adaptation of the original C language libghostty-vt documentation, using the officially supported Rust bindings and slightly altered to reflect how it should idiomatically be used in Rust.
While the two sources should be largely consistent, the C documentation should be seen as the more authoritative source in case of conflicting information.
libghostty-vt is a portable, high-performance C library for terminal emulation, with officially supported bindings for Rust and more. It is open source and MIT licensed.
- It is highly generic: you give it the bytes a program writes, and it processes and exposes the state of the terminal such as the screen, the cursor, the scrollback, etc.
- It is highly portable: we build and test libghostty-vt for Linux, macOS, iOS, Android, FreeBSD, Windows, WebAssembly, and bare-metal RISC-V and ARM. It works on 32-bit and 64-bit systems.
- It is high-performance: the IO throughput is best-in-class and faster than any other known terminal emulator. Memory usage is highly optimized, one libghostty-vt consumer was able to run 10,000 active (input/output) terminals with a running shell on a 4 core 8 GB Linux machine.
- It has no dependencies: For the highest performance, the library only needs libc, but you can optionally build it without that requirement and it can be fully freestanding on its own and run directly on hardware.
You can use libghostty-vt to build:
- Terminal emulators and multiplexers
- Web terminals and remote sessions
- Session recording and playback
- Test harnesses for TUI apps
- Agents and automation that read what a TUI is showing
- Etc.
libghostty-vt was originally extracted from Ghostty, but since then is in use by hundreds of projects both free and commercial. We don’t have any tracking of course but by our best estimates libghostty-vt is used by tens of millions of people daily across every major desktop and mobile platform.
Where to Next?
- Getting the library? See Installing.
- Building a terminal? Read Your First Terminal.
- Only need one piece? The parsers and encoders work without a terminal. See Building Blocks and Input.
- Read API Conventions for general library-wide conventions.
Example
Here is a complete program. It creates a terminal, writes some text with a color sequence in it, and prints what ended up on the screen.
use libghostty_vt::{Terminal, error::Error, fmt::Formatter};
fn main() -> Result<(), Error> {
// Create an 80x24 terminal with the default allocator.
let mut terminal = Terminal::new(80, 24)?;
// Write the bytes a program would send. They can come from anywhere: a pty,
// a network connection, a recording. The escape sequences make "world" bold
// and green.
terminal.vt_write(b"Hello, \x1b[1;32mworld\x1b[0m!\r\n");
// Read the screen back. A new formatter emits plain text, so the styles
// don't appear in the output, but you can set options to enable that.
let mut formatter = Formatter::new(&terminal)?;
let buf = formatter.format_alloc(None)?;
println!("{}", buf.escape_ascii());
Ok(())
}
Full program: rust-vt-hello/src/main.rs
It prints Hello, world! in plain text. The color is in the terminal’s state
but the way we configured the formatter doesn’t show it. This has no GUI window
and doesn’t use a real PTY, but it is hopefully demonstrative of libghostty-vt
and how you could hook it up to both.