72 stable releases

2.2.5 Apr 4, 2021
2.2.4 Mar 28, 2021
2.2.2 Feb 18, 2021
2.1.3 Dec 31, 2020
1.2.4 Mar 24, 2020

#51 in Command-line interface

Download history 7/week @ 2020-12-19 24/week @ 2020-12-26 96/week @ 2021-01-02 28/week @ 2021-01-09 115/week @ 2021-01-16 55/week @ 2021-01-23 36/week @ 2021-01-30 124/week @ 2021-02-06 948/week @ 2021-02-13 85/week @ 2021-02-20 16/week @ 2021-02-27 45/week @ 2021-03-06 11/week @ 2021-03-13 149/week @ 2021-03-20 161/week @ 2021-03-27 170/week @ 2021-04-03

619 downloads per month
Used in 2 crates


5.5K SLoC


Crate API dependency status MSRV: 1.48.0


libnotcurses-sys is a Rust wrapper for the notcurses C library

This is a work in progress.

This library is built with several layers of zero-overhead abstractions over the C functions and pointers accessed through FFI.

How to use this library

There are basically two ways: The Rust way, and the C way. (Or a mix of both).

1. The Rust way

Where you use the safely wrapped types, with its methods and constructors, and painless error handling, like this:


use libnotcurses_sys::*;

fn main() -> NcResult<()> {
    let mut nc = FullMode::with_flags(NCOPTION_NO_ALTERNATE_SCREEN)?;
    let plane = nc.stdplane();
    plane.putstr("hello world")?;

Specifically [FullMode] and [DirectMode] are safe wrappers over [Notcurses] and [NcDirect], respectively.

FullMode and DirectMode both implement the [Drop], [AsRef], [AsMut], [Deref][std::ops::Deref] and [DerefMut][std::ops::DerefMut] traits.

Their destructors are called automatically at the end of their scope.

Methods are directly implemented for Notcurses and NcDirect, and are made automatically available to FullMode & DirectMode, minus some function overrides, like their destructors, plus the static methods that have to be recreated.

The rest of the types that allocate, like [NcPlane], [NcMenu], [NcReader]… have no higher level wrapping struct, they don't implement Drop, so they have to be *.destroy()ed manually.

But they do implement methods and use [NcResult] as the return type, for handling errors in the way we are used to in Rust.

For the types that don't allocate, most are based on primitives like i32, u32, u64… without a name in the C library. In Rust they are type aliased (e.g.: [NcChannel], [NcChannelPair], [NcRgb], [NcColor]…), to leverage type checking, and they implement methods through traits (e.g. [NcChannelMethods] must be in scope to use the NcChannel methods.

2. The C way

You can always use the C API functions directly if you prefer, in a very similar way as the C library is used.

It requires the use of unsafe, since most functions are wrapped directly by bindgen marked as such.

Error handling is done this way by checking the returned [NcIntResult], or in case of receiving a pointer, by comparing it to [null_mut()][core::ptr::null_mut].


use core::ptr::{null, null_mut};
use std::process::exit;

use libnotcurses_sys::*;

fn main() {
    let options = ffi::notcurses_options {
        termtype: null(),
        renderfp: null_mut(),
        loglevel: 0,
        margin_t: 0,
        margin_r: 0,
        margin_b: 0,
        margin_l: 0,
    unsafe {
        let nc = notcurses_init(&options, null_mut());
        if nc == null_mut() {
        let plane = notcurses_stdplane(nc);
        let cols = ncplane_putstr(&mut *plane, "hello world");
        if cols < NCRESULT_OK {
        if notcurses_stop(nc) < NCRESULT_OK {

The notcurses C API docs


~30K SLoC