Guide · Open source

How to use Terminal.Gui: install, first app and key features

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

Terminal.Gui is a cross-platform UI toolkit for .NET that lets you build interactive applications that run inside a terminal window, with widgets such as buttons, text fields, tables, trees, menus and dialogs. This guide shows you how to install it, run a template project, read a minimal C# example and find the controls you need. By the end you will know where to start and what the library is suited for.

Terminal.Guitui-cs/Terminal.Gui · ★ 11.3k · MIT Install options & downloads

Quick start

1Check your .NET SDK. Confirm the .NET SDK is installed. The README does not state a required version, so consult the project docs if unsure.
2Install the templates. Run dotnet new install Terminal.Gui.Templates to add the project templates.
3Create a project. Run dotnet new tui-simple -n myproj and change into the new folder.
4Run the app. Run dotnet run inside the project folder and check that the window appears.
5Explore the UI Catalog. Clone the repository and run the UI Catalog project to see the available controls.
6Read the simple example. Open the Hello World code and adjust the label text, then rebuild and run.
7Read the docs. Use the Getting Started Guide and Views Overview to pick widgets for your app.

What Terminal.Gui is and who it is for

Terminal.Gui is a library, not a finished application. You use it to build your own terminal UI apps in C#. It aims to behave the same on Windows, macOS and Linux/Unix and supports both keyboard and mouse input.

It fits C# and .NET developers who want forms, tables or menus in a terminal, and teams writing internal admin or configuration tools that run over SSH. If you work in Python, JavaScript or another non-.NET language, it is not the right toolkit.

Good fit: .NET developers building terminal tools with forms, tables or menus
Good fit: internal admin or configuration tools used over SSH
Good fit: CLI tools that need an in-line or full-screen interface
Not a fit: projects that need a graphical (non-terminal) interface

Install the .NET SDK and Terminal.Gui

The main prerequisite is the .NET SDK. The README does not specify which SDK version is required, so check the project documentation before you start. You can add the library to an existing project or install the project templates.

To add the library to a .NET project, run the first command below from the project folder. To install the templates, run the second command.

dotnet add package Terminal.Gui
dotnet new install Terminal.Gui.Templates

Create and run a starter TUI app

The quickest route is the template. Install the templates, create a new project from the tui-simple template, move into it and run it. The project name in this example is myproj; you can choose your own.

To explore every built-in control, the README points to the UI Catalog example in the repository. Run it from the root of a clone of the repository.

dotnet new install Terminal.Gui.Templates
dotnet new tui-simple -n myproj
cd myproj
dotnet run

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

Read a minimal Terminal.Gui program

The simple example creates an application instance, initialises it, adds a window with a label centred on screen, and runs the window. Press Esc to quit, as the window title says.

Note the v2 namespaces used in the example: Terminal.Gui.App, Terminal.Gui.ViewBase and Terminal.Gui.Views. Older v1 code may not compile against these imports, so the migration guide is worth reading if you are porting an existing app.

Application.Create() creates the application instance
app.Init() prepares the terminal
Window and Label are views you add to the hierarchy
app.Run(window) starts the event loop with the window

using Terminal.Gui.App;
using Terminal.Gui.ViewBase;
using Terminal.Gui.Views;

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);

Choose the right widgets and features

The README lists built-in widgets including text editors, buttons, checkboxes, trees, tables, markdown, linear ranges, menus and selectors. It also lists charts, progress indicators, colour pickers, file and directory browsers, and wizards for multi-step processes.

Layout uses positioning and sizing, such as Pos.Center, and the layout documentation covers adornments. Keyboard handling uses key bindings and commands, and themes and key bindings can be configured and persisted. The full list of controls is in the Views Overview.

Tables and tree views are described as scaling to many elements with sorting and filtering
Applications can run in-line, scrolling with the terminal, or full screen
Themes, colours and key bindings are customisable and persistable
TrueColor, Unicode and mouse support are included

Learn the architecture and go further

Before building anything large, read the Application Architecture page, which describes the instance-based model and the IRunnable pattern. The View documentation explains the view hierarchy and lifecycle, and the Getting Started Guide walks through a first application.

If you have existing v1 code, use the migration guide rather than guessing at the changes.

Getting Started Guide: tui-cs.github.io/Terminal.Gui/docs/getting-started
API Reference: tui-cs.github.io/Terminal.Gui/api/Terminal.Gui.App.html
Documentation index: tui-cs.github.io/Terminal.Gui/docs/index

What people use it for

Internal admin or configuration tools run over SSH
Forms and data entry screens in a console application
Browsing files and directories with search and filtering
Multi-step setup wizards with validation
CLI tools that scroll in-line with the terminal, or take over the full screen

Frequently asked questions

Is Terminal.Gui free to use?

Terminal.Gui is released under the MIT licence, as stated in the project listing. Check the licence file in the repository for the full terms before you ship a product.

What do I need to install Terminal.Gui?

You need the .NET SDK. Install the library with dotnet add package Terminal.Gui. The README does not specify an SDK version, so check the documentation for the version you target.

How do I install Terminal.Gui templates?

Run dotnet new install Terminal.Gui.Templates. Then create a project with dotnet new tui-simple -n myproj and run it with dotnet run.

Does Terminal.Gui work on Windows, macOS and Linux?

The project aims for a consistent experience on Windows, macOS and Linux/Unix. It also supports both keyboard and mouse input.

What are the alternatives to Terminal.Gui?

Other .NET options include Spectre.Console and Terminal.GUI.Net. For other languages, Textual is a Python option and Ratatui is a Rust option. Pick based on your language and the widgets you need.

Can I use Terminal.Gui from Python or JavaScript?

No. Terminal.Gui is a C# library for .NET, so you need to build your app in a .NET language. For Python, consider Textual instead.

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

Terminal.Gui suits C# and .NET developers who want a built-in set of widgets for forms, tables, menus and dialogs in a terminal app, including tools run over SSH. It is not a finished application, and it is the wrong choice if you need a graphical interface or work outside .NET.

Install options & downloads