Skip to content
Ncurses Nif for Elixir (or Erlang)
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


Build Status Hex version

Ncurses NIF for Elixir

What it does

ExNcurses is a NIF that let's you create text-based user interfaces and games. It connects Elixir to the ncurses library.

Differences from C ncurses

In general, this library provides a thin wrapper on most ncurses functions. That means that the documentation and examples for the C library should apply fairly directly. There are some differences:

  • #defines are now atoms. For exaample, instead of KEY_UP for up arrow, you'll receive the atom :up.
  • Keyboard input comes in as {ex_ncurses, :key, code} messages if you call listen/0. You can still call getch() like in C, but it doesn't have the semantics.
  • Functions that take printf style arguments in C are available, but don't support arguments. It's expected that programs construct strings in Elixir like normal..


The package is available on and can be installed by adding ex_ncurses to your list of dependencies in mix.exs:

def deps do
    {:ex_ncurses, "~> 0.3"}


You will need to install the ncurses library and C header files first. Do this however is appropriate for your system.

Then the project can be compiled with

mix deps.get
mix compile


To run any of the example scripts, start them by invoking the

./ demo

More examples can be found at:


Why isn't anything being drawn to the screen

Try calling ExNcurses.refresh/0 or ExNcurses.wrefresh/1 if you're working in a window.

Hold up, x and y are swapped everywhere

That's the ncurses way. Everything is row and then column, so y comes first. The upper left is (0, 0).

What happened to the Elixir console

It's still there. It won't receive any input between calls to ExNcurses.initscr/1/ExNcurses.newterm/3 and ExNcurses.endwin/0. I'm still on the fence with what to do with the console. It could be redirected, output could be thrown away, etc. At the moment, you'll likely want to turn on the Elixir console logger so that it doesn't interfere with the display.

Something is crashing Erlang! What do I do

Try editing src/ex_ncurses.c and uncomment the #define DEBUG line. This logs timing and function entry/exit information to ex_ncurses.log. If something crashes, it should hopefully provide more information. Please post an issue if you find a crash with the log and details on how to reproduce. Or if you're up to it, please send a Pull Request with a fix. We appreciate any help you can provide to make this a better library.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.