ncurses
Terminal user interfaces — windows, colours and keyboard handling in a text console.
What it is
ncurses is a programming library that provides an API for creating text-based user interfaces in a terminal-independent manner. It supports windows, colors, keyboard input, and mouse events in terminal applications.
ncurses allows developers to control cursor movement, handle keyboard input, display colored text, create multiple windows, and manage terminal screens efficiently. It is widely used for CLI-based applications, system monitors, text editors, and terminal games.
- Licence
- MIT-like (X11)
- Powers
- htop, vim, mc and most classic terminal tools
When to use it
The question documentation cannot answer for you — because it cannot recommend something else.
Reach for it when
- Building a full-screen terminal application such as an editor or monitor
- You need cursor positioning and colour that work across terminal types
Look elsewhere when
- Simple line-based CLI output — printf is enough and far simpler
Installation
sudo apt install libncurses5-dev libncursesw5-devGetting started
The smallest useful thing you can do with it, and what each part means.
#include <ncurses.h>
int main() {
initscr(); // Start ncurses mode
printw("Hello, ncurses!");
refresh(); // Print on screen
getch(); // Wait for user input
endwin(); // End ncurses mode
return 0;
}#include <ncurses.h>
int main() {
initscr();
start_color();
init_pair(1, COLOR_RED, COLOR_BLACK);
attron(COLOR_PAIR(1));
printw("Red Text");
attroff(COLOR_PAIR(1));
refresh();
getch();
endwin();
return 0;
}Advanced usage
Where the library earns its place over a simpler alternative.
#include <ncurses.h>
int main() {
initscr();
WINDOW *win1 = newwin(10, 20, 0, 0);
WINDOW *win2 = newwin(10, 20, 5, 25);
box(win1, 0, 0);
box(win2, 0, 0);
wrefresh(win1);
wrefresh(win2);
getch();
delwin(win1);
delwin(win2);
endwin();
return 0;
}#include <ncurses.h>
int main() {
initscr();
keypad(stdscr, TRUE);
printw("Press arrow keys (ESC to exit)\n");
int ch;
while((ch = getch()) != 27) {
switch(ch) {
case KEY_UP: printw("Up\n"); break;
case KEY_DOWN: printw("Down\n"); break;
case KEY_LEFT: printw("Left\n"); break;
case KEY_RIGHT: printw("Right\n"); break;
default: printw("Key code: %d\n", ch);
}
refresh();
}
endwin();
return 0;
}// Use <menu.h> and <form.h> headers to create interactive menus and forms (requires linking with -lmenu -lform).Errors and fixes
The failures you are most likely to hit, and what actually resolves them.
- Unable to initialize ncurses
- Ensure terminal supports ncurses and that your program links against `-lncurses`.
- KEY_* constants not recognized
- Call `keypad(stdscr, TRUE)` or on the specific window to enable special key input.
Best practices
- Always call `initscr()` before using ncurses functions and `endwin()` before exiting.
- Use `refresh()` and `wrefresh()` appropriately to update the screen or windows.
- Enable keypad mode when handling special keys.
- Use color pairs instead of direct color codes for portability.
- Clean up all windows with `delwin()` to avoid memory leaks.
Alternatives
Comparable options, and the reason you would pick one over the other.
termbox2
Much smaller and simpler alternative for basic TUI needs
Background
Why it exists, and what it was reacting to.
ncurses was developed as a free-software emulation of the proprietary curses library, originally created for BSD Unix systems. It enables developers to build interactive command-line applications with advanced text-based UIs, such as menus, forms, and dashboards.