Library for writing text-based user interfaces

Related tags

CLI termbox


This library is no longer maintained. It's pretty small if you have a big project that relies on it, just maintain it yourself. Or look for forks. Or look for alternatives. Or better - avoid using terminals for UI. Never the less, thanks to all who ever contributed.


Termbox is a library that provides minimalistic API which allows the programmer to write text-based user interfaces.

It is based on a very simple abstraction. The main idea is viewing terminals as a table of fixed-size cells and input being a stream of structured messages. Would be fair to say that the model is inspired by windows console API. The abstraction itself is not perfect and it may create problems in certain areas. The most sensitive ones are copy & pasting and wide characters (mostly Chinese, Japanese, Korean (CJK) characters). When it comes to copy & pasting, the notion of cells is not really compatible with the idea of text. And CJK runes often require more than one cell to display them nicely. Despite the mentioned flaws, using such a simple model brings benefits in a form of simplicity. And KISS principle is important.

At this point one should realize, that CLI (command-line interfaces) aren't really a thing termbox is aimed at. But rather pseudo-graphical user interfaces.


Termbox comes with a waf-based build scripts. In order to configure, build and install it, do the following::

./waf configure --prefix=/usr                                (configure)
./waf                                                        (build)
./waf install --destdir=DESTDIR                              (install)

By default termbox will install the header file and both shared and static libraries. If you want to install a shared library or static library alone, use the following as an install command::

./waf install --targets=termbox_shared --destdir=PREFIX      (shared library)


./waf install --targets=termbox_static --destdir=PREFIX      (static library)

In order to install the python module, use the following command (as root or via sudo)::

python install

for Python 3::

python3 install

Getting started

Termbox's interface only consists of 12 functions::

tb_init() // initialization
tb_shutdown() // shutdown

tb_width() // width of the terminal screen
tb_height() // height of the terminal screen

tb_clear() // clear buffer
tb_present() // sync internal buffer with terminal

tb_blit() // drawing functions

tb_select_input_mode() // change input mode
tb_peek_event() // peek a keyboard event
tb_poll_event() // wait for a keyboard event

See src/termbox.h header file for full detail.


If you want me to add your Termbox project here, send me a pull request or drop a note via email, you can find my email below.

Language bindings
Other implementations

Bugs & questions

Report bugs to the issue tracker. Send rants and questions to me: [email protected].



  • Properly include changelog into the tagged version commit. I.e. I messed up by tagging v1.1.1 and describing it in changelog after tagged commit. This commit marked as v1.1.2 includes changelog for both v1.1.1 and v1.1.2. There are no code changes in this minor release.



  • API: tb_width() and tb_height() are guaranteed to be negative if the termbox wasn't initialized.
  • API: Output mode switching is now possible, adds 256-color and grayscale color modes.
  • API: Better tb_blit() function. Thanks, Gunnar Zötl [email protected].
  • API: New tb_cell_buffer() function for direct back buffer access.
  • API: Add new init function variants which allow using arbitrary file descriptor as a terminal.
  • Improvements in input handling code.
  • Calling tb_shutdown() twice is detected and results in abort() to discourage doing so.
  • Mouse event handling is ported from termbox-go.
  • Paint demo port from termbox-go to demonstrate mouse handling capabilities.
  • Bug fixes in code and documentation.


  • Remove the Go directory. People generally know about termbox-go and where to look for it.
  • Remove old terminfo-related python scripts and backport the new one from termbox-go.
  • Remove cmake/make-based build scripts, use waf.
  • Add a simple terminfo database parser. Now termbox prefers using the terminfo database if it can be found. Otherwise it still has a fallback built-in database for most popular terminals.
  • Some internal code cleanups and refactorings. The most important change is that termbox doesn't leak meaningless exported symbols like 'keys' and 'funcs' now. Only the ones that have 'tb_' as a prefix are being exported.
  • API: Remove unsigned ints, use plain ints instead.
  • API: Rename UTF-8 functions 'utf8_' -> 'tb_utf8_'.
  • API: TB_DEFAULT equals 0 now, it means you can use attributes alones assuming the default color.
  • Move python module to its own directory and update it due to changes in the termbox library.
  • Documentation of C functions missing

    Documentation of C functions missing

    Maybe I simply don’t see it, but there is no function documentation in the C headers and hardly any comments in the source files.

    The Python bindings are documented, though.

    How come?

    opened by Profpatsch 25
  • keyboard input broken on OSX Terminal

    keyboard input broken on OSX Terminal


    I ran into some other problems, this time the wait_fill_event() function would hang on a keypress. Window resize worked fine. I traced the problem to fread() in termbox.c on line 428. It would always return 0 and control would jump back to while(1), going on forever. Turns out, some previous operation on *in descriptor had caused an EOF error and therefor all subsequent freads fail. Placing clearerr(in) before fread() solved the problem for me.


    opened by guncha 18
  • Add CMake build option and include it in the readme

    Add CMake build option and include it in the readme

    Some people probably want to use CMake to include termbox in their project. Waf is also not used a lot throughout the C/C++ community, but I'm leaving that as is.

    opened by rikvdh 12
  • Crash on terminal resize when waiting for events.

    Crash on terminal resize when waiting for events.

    I'm not sure precisely what's going on, though I've managed to narrow it down to what I believe to be the smallest crashing piece of code (if it was real code I'd probably issue a close() at the end, but it never gets there anyway in this demonstration).

    If I run the following script:

    import termbox
    tb = termbox.Termbox()
    while True:

    and then attempt to resize my terminal (both when resizing panes in tmux and resizing an xterm that it's running directly under), more often than not python will abort, simply dumping out this message:

    python3.2: src/termbox.c:521: wait_fill_event: Assertion `r > 0' failed.

    This also happens when using peek_event, and does not seem to be affected by the timeout passed to peek_event. It does not occur on key events, at least so far as I can tell.

    As I said before, I'm really not sure what's going on here, and I don't imagine what I've got so far is all that helpful, so any advice on how to get a more useful crash dump would be much appreciated.

    opened by jesskay 10
  • Pressing ESC after setting the mode to TB_MOUSE_INPUT triggers assertion error

    Pressing ESC after setting the mode to TB_MOUSE_INPUT triggers assertion error

    It triggers this assertion.

    The program is:

    #include "termbox.h"
    int main(int argc, char **argv) {
        struct tb_event ev;
        return 0;

    See also: gchp/rustbox#32

    opened by sru 9
  • Replace waf with Makefile

    Replace waf with Makefile

    Using Python to build a C library seems a bit... odd. Makefiles have been around for decades, and work perfectly for both small and large projects.

    Makefiles have the advantage of being ubiquitous across UNIX-like systems. Anyone with a C compiler will have make, but a lot of people with C compilers won't have Python, and many of those won't want to install it just to build a single library.

    Portability aside, Makefiles are a lot easier for contributors as well as for people who just want to use the library. Almost everyone who knows C can write, or at least understand, a Makefile, making it easier to contribute to projects that use them.

    I removed the src and build directories because the root of the repo felt a bit empty with only src, README.rst and COPYING. It's easy enough to add them back in if necessary though, so let me know.

    This also resolves issue #93, partly because I wanted to remove all Python code from the repo and partly because I couldn't be bothered to work out how the wrapper is generated and integrate that into the Makefile. Let me know if you'd prefer to keep it in and I'll see what I can do.

    opened by silversquirl 7
  • Cygwin peek/poll_event asserts wait_fill_event first read

    Cygwin peek/poll_event asserts wait_fill_event first read

    Using the same sequence of steps as keyboard.c, I get an assert in the very first block of reading code of wait_fill_event (currently line 581).

    I'm using the latest 32-bit Cygwin on Win7/64. Since I'm using CMake I made a static library for termbox.c and utf8.c to live in.

    I tried disabling the initial reading section of wait_fill_event, and that worked, until a resize occurred. Upon resizing the block of reading code in the while loop (currently line 613) would assert on errno==EAGAIN.

    opened by cardiffman 7
  • no mouse events in xterm and xfce4-terminal

    no mouse events in xterm and xfce4-terminal

    Using the termbox keyboard demo. The mouse events are reported as keyboard events, the reported key values appear to be random. Also, in xterm the box drawing characters are drawn as â.

    Arch Linux, xterm 325, xfce4-terminal 0.6.3, termbox trunk, $TERM = xterm

    opened by maep-- 6
  • "cygwin" terminal support

    Steps to reproduce:

    1. From cygwin, ssh to a linux machine.
    2. ./keyboard tb_init() failed with error code -1

    Note in this scenario $TERM == "cygwin".

    opened by thejoshwolfe 6
  • Handle NUL code point in tb_utf8_unicode_to_char.

    Handle NUL code point in tb_utf8_unicode_to_char.

    This is a bit semantic, but assuming the return value of tb_utf8_unicode_to_char is supposed to represent the length (as in strlen) of the resulting UTF-8 string out, a NUL code point should result in a 0-length string, not 1-length.

    opened by adsr 5
  • invalid pointer in tb_shutdown()

    invalid pointer in tb_shutdown()

    *** Error in `/home/lukas/Hacking/c/tinyrl/bin/tinyrl': munmap_chunk(): invalid pointer: 0x0000000000607f80 ***
    ^[[C======= Backtrace: =========
    ======= Memory map: ========
    00400000-00406000 r-xp 00000000 fe:03 3932165                            /home/lukas/Hacking/c/tinyrl/bin/tinyrl
    00606000-00607000 rw-p 00006000 fe:03 3932165                            /home/lukas/Hacking/c/tinyrl/bin/tinyrl
    00607000-00676000 rw-p 00000000 00:00 0                                  [heap]
    7ffff751d000-7ffff7533000 r-xp 00000000 fe:04 13590                      /usr/lib/
    7ffff7533000-7ffff7732000 ---p 00016000 fe:04 13590                      /usr/lib/
    7ffff7732000-7ffff7733000 rw-p 00015000 fe:04 13590                      /usr/lib/
    7ffff7733000-7ffff78cc000 r-xp 00000000 fe:04 13264                      /usr/lib/
    7ffff78cc000-7ffff7acc000 ---p 00199000 fe:04 13264                      /usr/lib/
    7ffff7acc000-7ffff7ad0000 r--p 00199000 fe:04 13264                      /usr/lib/
    7ffff7ad0000-7ffff7ad2000 rw-p 0019d000 fe:04 13264                      /usr/lib/
    7ffff7ad2000-7ffff7ad6000 rw-p 00000000 00:00 0 
    7ffff7ad6000-7ffff7bd9000 r-xp 00000000 fe:04 13263                      /usr/lib/
    7ffff7bd9000-7ffff7dd9000 ---p 00103000 fe:04 13263                      /usr/lib/
    7ffff7dd9000-7ffff7dda000 r--p 00103000 fe:04 13263                      /usr/lib/
    7ffff7dda000-7ffff7ddb000 rw-p 00104000 fe:04 13263                      /usr/lib/
    7ffff7ddb000-7ffff7dfd000 r-xp 00000000 fe:04 13237                      /usr/lib/
    7ffff7ff3000-7ffff7ff8000 rw-p 00000000 00:00 0 
    7ffff7ff8000-7ffff7ffa000 r--p 00000000 00:00 0                          [vvar]
    7ffff7ffa000-7ffff7ffc000 r-xp 00000000 00:00 0                          [vdso]
    7ffff7ffc000-7ffff7ffd000 r--p 00021000 fe:04 13237                      /usr/lib/
    7ffff7ffd000-7ffff7ffe000 rw-p 00022000 fe:04 13237                      /usr/lib/
    7ffff7ffe000-7ffff7fff000 rw-p 00000000 00:00 0 
    7ffffffde000-7ffffffff000 rw-p 00000000 00:00 0                          [stack]
    ffffffffff600000-ffffffffff601000 r-xp 00000000 00:00 0                  [vsyscall]

    I recently experienced this strange error when my program quitted. It is related to tb_shutdown() as I found out by using valgrind: valgrind error. I don't have any idea how to fix this yet.

    opened by sternenseemann 5
  • tb_peek_event() buffers inputs with sleep_for() c++11

    tb_peek_event() buffers inputs with sleep_for() c++11

    I'm not sure if this behavior of tb_peek_event() is intentional or not. I encountered it while attempting to make Tetris using termbox and trying to implement a time function and any inputs would stack rather than update on loop.

    It can be replicated like this:

    simply hold space and release when it shows 1.

    #include <termbox.h> #include <thread> #include <chrono> int main(void) { int i; tb_init(); tb_cell c = {}; tb_event e = {}; while(i < 4) { tb_clear(); std::this_thread::sleep_for(std::chrono::milliseconds(2000)); tb_peek_event(&e, 0); if(e.key == TB_KEY_SPACE) { i++; } = 48 + i; tb_put_cell(0,0,&c); tb_present(); } tb_shutdown(); return(0); }

    opened by Mutaru16bit 1
  • Allow reading the front buffer?

    Allow reading the front buffer?

    Feature request/idea: reading the front buffer

    A function like tb_cell_buffer for the front buffer would be nice to have. I realize it comes with some amount of risk. If there is interest, I'd be happy to prototype something.

    My use case is below, but I think this could be helpful in a more generic sense:

    I've made a mini termbox based window manager of sorts and would like to implement some type of modal functionality. I'd like to be able to push the contents of the front buffer on a stack, show a modal, and then display the previous front buffer again after the modal is closed.

    Since each section of my terminal is managed by an arbitrary number of window objects, it is impractical and inefficient to track their states manually.

    opened by josharenson 0
  • Are extended terminfo files being correctly parsed?

    Are extended terminfo files being correctly parsed?

    Code contains #define TI_ALT_MAGIC 542, which is the alternative header for terminfo "extended storage format". This is ultimately used to correctly calculate the strings offset into the compiled terminfo database.

    However, term(5) states that the alt magic is 0542, which is octal. TI_ALT_MAGIC should be set to (int)354, or prefixed with a zero.

    I don't have any extended storage format terminfo files handy, but I am happy to test if you point me to where I can get some.

    opened by mlabbe 2
  • Documentation of the API could be more helpful

    Documentation of the API could be more helpful

    The README says "Termbox's interface only consists of 12 functions", which is not really accurate (there's 21 functions), and lists just the function names. I think it would be helpful to give argument names (e.g. tb_change_cell(x, y, ch, fg, bg) instead of just tb_change_cell()) and either list all 21 functions, or explicitly say that the listed functions are only the most commonly used ones, but the API has a some other functions too.

    opened by bruce-hill 1
  • Add tb_poll_fds() to obtain file descriptors for polling

    Add tb_poll_fds() to obtain file descriptors for polling

    This adds a function to obtain file descriptors from termbox that can be be polled for IO-readiness. This can be used to integrate termbox into an event loop like asyncio or curio in python, or libuv in C, so the program can process other things (like network sockets) asynchronously with UI events.

    The idea is to use tb_poll_fds() to get a set of descriptors, register them for polling (e.g. with EPOLLIN), and when any events arrive, the next tb_poll_event() can be expected to complete quickly.

    (edit: markdown formatting and C usage example)

    opened by tobyp 2
A library for interactive command line interfaces in modern C++

cli A cross-platform header only C++14 library for interactive command line interfaces (Cisco style) Features Header only Cross-platform (linux and wi

Daniele Pallastrelli 888 Dec 31, 2022
Library for creating terminal applications with text-based widgets

Library for creating terminal applications with text-based widgets FINAL CUT is a C++ class library and widget toolkit with full mouse support for cre

Markus Gans 724 Dec 30, 2022
Small header only C++ library for writing multiplatform terminal applications

Terminal Terminal is small header only library for writing terminal applications. It works on Linux, macOS and Windows (in the native cmd.exe console)

Jupyter Xeus 274 Jan 2, 2023
Command-Based Text Editor written in cpp using Linked Lists and Stack

Command Based Text Editor Our goal in this project is to write a command-based text editor in cpp using linked lists and stack. This text editor will

bedirhanbardakci 3 Jun 9, 2021
udmp-parser: A Windows user minidump C++ parser library.

udmp-parser: A Windows user minidump C++ parser library. This is a cross-platform (Windows / Linux / OSX / x86 / x64) C++ library that parses Windows

Axel Souchet 95 Dec 13, 2022
Draw sequence diagram in text from terminal.

sequence-diagram-cli Draw seqence diagram from terminal.

null 44 Dec 20, 2022
Add a scrollbar to the kakoune text editor (experimental!)

Scrollbar.kak This is a scrollbar for kakoune, the educated programmer's terminal editor of choice. It uses the line-flagging feature and a compiled s

Sawdust & Diamonds 12 Nov 9, 2021
led is a line-oriented text editor in command line

led is a line-oriented text editor in command line. This editor is similar to the standard program on unix systems - GNU ed. But i'm not going to make an exact clone of that program, it's just a pet project.

Artem Mironov 16 Dec 27, 2022
:computer: C++ Functional Terminal User Interface. :heart:

FTXUI Functional Terminal (X) User interface A simple C++ library for terminal based user interface. Demo: Feature Functional style. Inspired by [1] a

Arthur Sonzogni 4k Jan 3, 2023
Alternative firmware for IP cameras based on the HiSilicon (and other) SoC's

OpenIPC v2.1 (experimental, buildroot based..) Alternative firmware for IP cameras based on the HiSilicon (and other) SoC's More information about the

OpenIPC 363 Jan 7, 2023
The KISS file manager: CLI-based, ultra-lightweight, lightning fast, and written in C

CliFM is a CLI-based, shell-like (non-curses) and KISS terminal file manager written in C: simple, fast, and lightweight as hell

leo-arch 819 Jan 8, 2023
Fegeya Freud, CLI FPaper renderer, based on Totem (`less`-like tool without `--help`)

Fegeya Freud, CLI FPaper renderer, based on Totem (`less`-like tool without `--help`)

Ferhat Geçdoğan 3 Jun 11, 2021
sc4cpp is a shellcode framework based on C++

sc4cpp is a shellcode framework based on C++

null 72 Jan 7, 2023
Simple, command line based player toolkit for the Ironsworn tabletop RPG

isscrolls - Command line based player toolkit for the Ironsworn tabletop RPG isscrolls is a simple toolkit for players of the Ironsworn tabletop RPG.

null 7 Sep 9, 2022
A C-based Mini Shell: mumsh

A C-based Mini Shell: mumsh This project is a course project in VE482 Operating System @UM-SJTU Joint Institute. In this project, a mini shell mumsh i

Kexuan Huang 5 Sep 28, 2022
Traffic capture and intercept program based on Windows Filtering Platform (WFT)

Traffic capture and intercept program based on Windows Filtering Platform (WFT)

null 2 Oct 17, 2021
BCJR-based decoder for CCSDS turbo codes (according to CCSDS 131.0-B-3)

ccsds-tc ccsds-tc is a small project that attempts to systematize the decoding of space packets as received by ground stations of the Amateur DSN. Thi

Gonzalo José Carracedo Carballal 9 Feb 23, 2022
A CLI based solver for the popular word guessing game WORDLE

Project WAR WAR stands for Wordle Answer and Resolver About Wordle is a web-based word game developed by Welsh-born software engineer Josh Wardle, for

Yeluri Ketan 2 Feb 19, 2022
A simple header-only C++ argument parser library. Supposed to be flexible and powerful, and attempts to be compatible with the functionality of the Python standard argparse library (though not necessarily the API).

args Note that this library is essentially in maintenance mode. I haven't had the time to work on it or give it the love that it deserves. I'm not add

Taylor C. Richberger 1.1k Jan 4, 2023