Terminal.Gui: a widget toolkit for .NET that renders inside someone else's terminal

What the toolkit claims to cover

The project describes itself as a cross-platform UI toolkit for building terminal UI applications on Windows, macOS, and Linux/Unix, and the feature list is long enough to be worth sorting by kind.

Rendering claims come first. The layout system is described as responsive, by analogy to responsive web pages, and the drawing model as fast and double-buffering-based, with tables and tree views said to scale to infinite elements with sorting and filtering. Colors and glyphs lean on TrueColor and Unicode, and the file browsers are said to support Nerd fonts with coloring.

Widgets are the second group: text editors, buttons, checkboxes, trees, tables, markdown, linear ranges, menus, and selectors. The text editor entry claims clipboard support, undo and redo, and Unicode handling. Visualization covers charts, graphs, progress indicators, and color pickers. Workflow widgets include wizards and multi-step processes with navigation and validation.

Two entries are worth pausing on because they describe a design decision rather than a widget. Apps can work in-line, scrolling with the terminal the way command line coding assistants do, or full screen taking over the display. And configuration covers themes, colors, key bindings, and settings that are customizable and persistable, rather than hardcoded.

The README points at a Views Overview page for the actual control list and a What's New in v2 page for architectural changes, which is where the list above stops being a summary and starts being a reference.

Getting a window on screen with four commands

There are two documented install paths and they amount to the same package. The direct one adds the NuGet package:

dotnet add package Terminal.Gui

The other installs a template pack, which gives you a project scaffold rather than only a library reference:

dotnet new install Terminal.Gui.Templates

From there the quick start is a create, a change directory, and a run:

dotnet new tui-simple -n myproj
cd myproj
dotnet run

The minimal program that template produces is short enough to read in full, and it shows the three-part shape of every v2 application. You create an application and initialise it, you build a view hierarchy, and you run the window:

using IApplication app = Application.Create ();
app.Init ();

using Window window = new () { Title = "Hello World (Esc to quit)" };
Label label = new ()
{
    Text = "Hello, Terminal.Gui v2!",
    X = Pos.Center (),
    Y = Pos.Center ()
};
window.Add (label);

app.Run (window);

Three details in that snippet carry the v2 design. Positions are `Pos` expressions rather than integer coordinates, so centring is a calculation the layout system performs rather than a number you guess. Adding views is done on a parent rather than by passing them to the constructor. And the application is a disposable object created explicitly, rather than a global static you call into.

For exploring what exists before writing anything, the README recommends the UI Catalog, which is in the repository under `Examples/`:

dotnet run --project Examples/UICatalog/UICatalog.csproj

That is the fastest way to answer what the toolkit can do, because it exercises every control rather than describing them.

The v2 architecture, and where the docs for it live

The documentation index is organised into a set of deep dives that map onto the library's actual structure, and reading their titles tells you how the project thinks about its own layers.

Application Architecture covers the instance-based model and the `IRunnable` pattern. That is the change from v1 in one phrase: an application is an object you hold, and something that can be run is anything implementing an interface, rather than a static entry point. Layout System covers positioning, sizing, and adornments, which are the three things `Pos` and its siblings exist to control. Keyboard Handling covers key bindings and commands, View Documentation covers the view hierarchy and lifecycle, and Configuration covers themes and persistent settings.

There is a documentation inconsistency worth knowing about if you follow links from release notes rather than from the README. The README links everything under `tui-cs.github.io/Terminal.Gui/docs/`, while the 2.5.0 beta release notes point at a different host and path, `gui-cs.github.io/Terminal.GuiV2Docs/docs/`. The two are not the same location. The README set is the current one, so use it as your map and treat the older path in release notes as historical.

The repository itself is arranged the way you would expect for a large .NET solution, with `Terminal.Gui/` for the library, `Terminal.Gui.Analyzers.Internal/` and `Terminal.Gui.Interop.Spectre/` as separate projects, `Tests/`, `Examples/`, `Tools/`, `docfx/` for documentation, and `specs/` for design documents. Versioning comes from `GitVersion.yml`, and there is an `llms.txt` at the root alongside several agent instruction files, which tells you something about how the project expects to be worked on.

Version 2.5.0 removed things in a minor release

This is the part of the project you need to plan around before committing to it, and the release notes state it without softening. The 2.5.0 notes say the version is a minor bump because v2 still accepts planned API breaks, and that applications which compiled against 2.4.17 may need source changes.

Three specific removals are listed. `View.Text` is no longer virtual, and validation or cancellation moves to `OnTextChanging(string proposedValue)` and the `TextChanging` event, with `OnTextChanged()` for work after the change. `IAcceptTarget` moved to the `Terminal.Gui.Input` namespace, which is a one-line using directive fix. And the legacy `ConfigurationManager` is gone entirely, replaced by `TuiConfigurationBuilder` and settings POCOs such as `ButtonSettings.Current`.

The configuration removal has a migration story attached, and it is specific. The `config.json` format is now nested only, old flat-key files are converted with `Tools/MigrateConfig`, and types that were marked obsolete in 2.4.17 have been removed rather than kept around. If you have a flat config file from an earlier 2.x, that tool is the documented path rather than a hand edit.

The features shipped alongside are less dramatic: an editable NumericUpDown, horizontal scrolling in TableView for wide content, native ANSI size detection, a SynchronizationContext fix, and a change to the Kitty input protocol that preserves repeated legacy input after detection. That last one is the kind of fix that only matters on terminals with advanced input support, and it is a good signal about how much of the work is compatibility with real terminal emulators rather than drawing text.

What v2.4.17 says about the project's routine

Reading the 2.4.17 release notes is a useful corrective to any impression that this project ships large features on a schedule. The list is dominated by dependency bumps handled by dependabot, including GitVersion.MsBuild, Microsoft.Extensions.Options, Microsoft.Net.Compilers.Toolset, Spectre.Console, and gittools/actions, each moving by a patch version.

Alongside those are targeted fixes to FileDialog and OpenDialog behaviour, one restoring hidden and system entries such as dotfiles after a change to how inaccessible paths are ignored, and a back-merge of 2.4.16 from main into the develop branch. There is also a change to a width and height event contract.

Two things follow from that. First, the project keeps a `develop` default branch with a stable line alongside it, which is why 2.4.17 exists as a maintenance release at all. Second, the dependency surface includes Spectre.Console, which has its own interop project in the repository, so part of what this toolkit does is bridge to another console library rather than reimplement everything from nothing.

The last push to the develop branch was on 2026-09-21, ten days after 2.5.0 shipped on 2026-09-11, so the tip of the default branch is already ahead of the current stable release. If you read source to understand behaviour, keep in mind which version you are actually compiling against.

When a TUI is the right call and when it is not

The toolkit's own README suggests the case for this kind of interface by naming what it builds: CLI tools that scroll with the terminal, like the coding assistants many developers now use daily. That is the honest framing. A TUI makes sense when the tool runs on a remote machine, over SSH, or in a container where no graphical display exists, and the interaction is richer than a sequence of prompts but does not need a browser.

The strength is that everything degrades to the terminal you already have. No X server, no window manager, no runtime to install. The cost is that you are constrained by what the terminal emulator will render, and the library's job is to work around the differences between them. The TrueColor support, the Nerd font support, the Kitty input protocol handling, and the native ANSI size detection listed in recent releases are all the same problem seen from four sides.

The comparison to write down for yourself is against the alternatives you already have. For a .NET console tool, the built-in `System.Console` API is enough when you need prompts and progress bars, and it has no dependencies. A library like Spectre.Console covers tables and markup with much less surface to learn. Terminal.Gui earns its place when you need the widget set that those two do not provide, particularly dialogs, menus, and editable text, without pulling in a browser engine.

Whichever way you go, the UI Catalog is the deciding tool. If your planned interface is represented in it, you have found the widget. If it is not, you are writing it yourself and the toolkit is only buying you the drawing layer.

Editorial conclusion

Terminal.Gui is the right answer when a .NET tool needs more interaction than a prompt loop can carry but cannot assume a display server exists. It ships the widgets that such tools normally have to reinvent: tables with sorting and filtering, file dialogs, menus, text editing with undo and clipboard, charts, and wizards. The two costs are visible in the release notes rather than hidden. Version 2.5.0 removed a virtual property and deleted the legacy configuration manager in a minor bump, which is a deliberate policy for the v2 line and a real cost if you ship a library that depends on it. And the default branch is `develop`, so the code you read is ahead of the code you install. Start from the tui-simple template, run the UI Catalog to see what exists, and read the v1 to v2 migration guide before porting anything.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. tui-cs/Terminal.Gui on GitHub