Library for writing text-based user interfaces

Related tags

Utilities 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
libnpy is a simple C++ library for reading and writing of numpy's .npy files.

C++ library for reading and writing of numpy's .npy files

Leon Merten Lohse 142 Jun 21, 2022
Group project: writing our own printf function

0x11. C - printf By Julien Barbier, co-founder & CEO Concepts For this project, students are expected to look at these concepts: Group Projects Pair P

Pericles ADJOVI 3 Jun 4, 2022
Writing our own printf function, this is a project done under ALX Low Level Programming.

0x11. C - printf Writing our own printf function, this is a project done under ALX Low Level Programming. Resource secrets of printf Implementing prin

Ephantus Mwangi 3 Apr 18, 2022
a cpp lib for csv reading and writing

CSV Reader and Writer Author : csl E-Mail : [email protected] OverView Comma separated values (CSV, sometimes called character separated values, becau

null 0 Apr 3, 2022
An easy-to-use C library for displaying text progress bars.

What is this thing? progressbar is a C-class (it's a convention, dammit) for displaying attractive progress bars on the command line. It's heavily inf

Trevor Fountain 426 Jun 15, 2022
The libxo library allows an application to generate text, XML, JSON, and HTML output using a common set of function calls. The application decides at run time which output style should be produced.

libxo libxo - A Library for Generating Text, XML, JSON, and HTML Output The libxo library allows an application to generate text, XML, JSON, and HTML

Juniper Networks 240 Jun 13, 2022
Rich text library supporting customizable Markdown formatting

Rich text library supporting customizable Markdown formatting

Brace Yourself Games 76 Jun 12, 2022
A header only C++ library that provides type safety and user defined literals for physical units

SI - Type safety for physical units A header only c++ library that provides type safety and user defined literals for handling pyhsical values defined

Dominik Berner 374 Jun 15, 2022
Mustache text templates for modern C++

About Mustache implementation for modern C++ (requires C++11) Header only Zero dependencies Templated string type for compatibility with any STL-like

Kevin Wojniak 284 Jun 17, 2022
Read Non-Rectangular Text Data

meltr The goal of ‘meltr’ is to provide a fast and friendly way to read non-rectangular data (like ragged forms of ‘csv’, ‘tsv’, and ‘fwf’). Standard

R infrastructure 25 May 3, 2022
A c++ file just to show how can we change color of Background and Text in C++...

A c++ file just to show how can we change color of Background and Text in C++...

null 1 Nov 2, 2021
Windows user-land hooks manipulation tool.

MineSweeper Windows user-land hooks manipulation tool. Highlights Supports any x64/x86 Windows DLL (actually, any x64/x86 Windows PE for that matter)

Arsenii Pustovit 126 Jun 15, 2022
Immediate Human User Interface

ImHui Immediate Human User Interface Inspired by Dear ImGui. The purpose of this project is to learn more about how Immedate Mode GUIs actually work.

Tsoding 35 Jun 23, 2022
libparser is a small C library that parses input based on a precompiled context-free grammar.

libparser is a small C library that parses input based on a precompiled context-free grammar.

Mattias Andrée 9 Mar 11, 2022
A fast character conversion and transliteration library based on the scheme defined for Japan National Tax Agency (国税庁) 's corporate number (法人番号) system.

jntajis-python Documentation: What's JNTAJIS-python? JNTAJIS-python is a transliteration library, specifically

Open Collector, Inc. 12 May 16, 2022
C string library based on string ends

C string library based on string ends

Leah Neukirchen 18 Jun 8, 2022
WAFer is a C language-based software platform for scalable server-side and networking applications. Think node.js for C programmers.

WAFer WAFer is a C language-based ultra-light scalable server-side web applications framework. Think node.js for C programmers. Because it's written i

Riolet Corporation 692 Jun 3, 2022
Fast comparison-based sort algorithm

nanosort Algorithm nanosort aims to be a fast comparison-based sorting algorithm, tuned for POD types of reasonably small sizes. nanosort implements a

Arseny Kapoulkine 36 May 24, 2022
Applications based on Wi-Fi CSI (Channel state information), such as indoor positioning, human detection

ESP-CSI The main purpose of this project is to show the use of ESP-WIFI-CSI. The human body detection algorithm is still being optimized. You can get

Espressif Systems 123 Jun 15, 2022