blingful character graphics/TUI library. definitely not curses.
What it is: a library facilitating complex TUIs on modern terminal emulators, supporting vivid colors, multimedia, threads, and Unicode to the maximum degree possible. Things can be done with Notcurses that simply can't be done with NCURSES. It is furthermore fast as shit.
What it is not: a source-compatible X/Open Curses implementation, nor a replacement for NCURSES on existing systems.
birthed screaming into this world by nick black ([email protected]) * c++ wrappers by marek habersack ([email protected]) * rust wrappers by José Luis Cruz ([email protected]) * python wrappers by igo95862 ([email protected]) * zig wrappers by Jakub Dundalek ([email protected])
for more information, see dankwiki and the man pages. in addition, there is Doxygen output. there is a mailing list which can be reached via [email protected] i wrote a coherent guidebook, which is available for free download (or paperback purchase).
notcurses-democovers most of the functionality of Notcurses.
If you're running Notcurses applications in a Docker, please consult "Environment notes" below. If you need Notcurses on Ubuntu Focal (20.04 LTS), you can run:
sudo add-apt-repository ppa:dankamongmen/notcurses sudo apt-get update
Notcurses abandons the X/Open Curses API bundled as part of the Single UNIX Specification. For some necessary background, consult Thomas E. Dickey's superb and authoritative NCURSES FAQ. As such, Notcurses is not a drop-in Curses replacement.
Wherever possible, Notcurses makes use of the Terminfo library shipped with NCURSES, benefiting greatly from its portability and thoroughness.
Notcurses opens up advanced functionality for the interactive user on workstations, phones, laptops, and tablets, possibly at the expense of e.g. some industrial and retail terminals. Fundamentally, Curses assumes the minimum and allows you (with effort) to step up, whereas Notcurses assumes the maximum and steps down (by itself) when necessary. The latter approach probably breaks on some older hardware, but the former approach results in new software looking like old hardware.
Why use this non-standard library?
Thread safety, and efficient use in parallel programs, has been a design consideration from the beginning.
A more orderly surface than that codified by X/Open: Exported identifiers are prefixed to avoid common namespace collisions. The library object exports a minimal set of symbols. Where reasonable,
static inlineheader-only code is used. This facilitates compiler optimizations, and reduces loader time. Notcurses can be built without its multimedia functionality, requiring a significantly lesser set of dependencies.
All APIs natively support the Universal Character Set (Unicode). The
nccellAPI is based around Unicode's Extended Grapheme Cluster concept.
Visual features including images, fonts, video, high-contrast text, sprites, and transparent regions. All APIs natively support 24-bit color, quantized down as necessary for the terminal.
Much of the above can be had with NCURSES, but they're not what NCURSES was designed for. On the other hand, if you're targeting industrial or critical applications, or wish to benefit from its time-tested reliability and portability, you should by all means use that fine library.
Minimum versions generally indicate the oldest version I've tested with; it may well be possible to use still older versions. Let me know of any successes!
Here's more information on building and installation.
Seven binaries are installed as part of Notcurses: *
lsthat displays multimedia in the terminal *
ncneofetch: a neofetch ripoff *
ncplayer: renders visual media (images/videos) *
nctetris: a tetris clone *
notcurses-demo: some demonstration code *
notcurses-input: decode and print keypresses *
notcurses-tester: unit testing
notcurses-demofrom a checkout, provide the
datadirectory via the
-pargument. Demos requiring data files will otherwise abort. The base delay used in
notcurses-democan be changed with
-d, accepting a floating-point multiplier. Values less than 1 will speed up the demo, while values greater than 1 will slow it down.
notcurses-testerlikewise requires that
data, populated with the necessary data files, be specified with
-p. It can be run by itself, or via
-DUSE_PANDOC=on(the default), a full set of man pages and XHTML will be built from
doc/man. The following Markdown documentation is included directly:
TERMenvironment variable and various terminal emulators.
TERMvariable is wrong, or that terminfo definition is out-of-date, you're going to have a very bad time. Use only
TERMvalues appropriate for your terminal. If this variable is undefined, or Notcurses can't load the specified Terminfo entry, it will refuse to start, and you will not be going to space today.
LANGenvironment variable is set to a UTF8-encoded locale, and that this locale has been generated. This usually means
en_US.UTF-8. The first part (
en_US) ought exist as a directory or symlink in
/usr/share/locales. This usually requires editing
locale-gen. On Debian systems, this can be accomplished with
dpkg-reconfigure locales, and enabling the desired locale. The default locale is stored somewhere like
If your terminal has an option about default interpretation of "ambiguous-width characters" (this is actually a technical term from Unicode), ensure it is set to Wide, not narrow (if that doesn't work, ensure it is set to Narrow, heh).
Notcurses primarily loads control sequences from
terminfo(5), using the database entry specified by the
TERMenvironment variable. 24-bit "TrueColor" color support (or at least the ability to specify 3 8-bit channels as arguments to
setbf) is indicated by the
rgbterminfo capability. Many terminals with RGB support do not advertise the
rgbcapability. If you believe your terminal to support 24-bit TrueColor, this can be indicated by exporting the
COLORTERMenvironment variable as
24bit. Note that some terminals accept a 24-bit specification, but map it down to fewer colors.
Fonts end up being a whole thing, little of which is pleasant. I'll write this up someday FIXME.
It is worth knowing that several terminals draw the block characters directly, rather than loading them from a font.
If things break or seem otherwise lackluster, please consult the Environment Notes section! You need to have a correct
LANGdefinition, and probably want
Q: The demo fails in the middle of
intro. A: Check that your
TERMvalue is correct for your terminal.
introdoes a palette fade, which is prone to breaking under incorrect
TERMvalues. If you're not using
TERMshould not be
Q: Can I have Notcurses without this huge multimedia stack? A: Yes! Build with
Q: Notcurses looks like absolute crap in
screendoesn't support RGB colors (at least as of 4.08.00); if you have
COLORTERMdefined, you'll have a bad time. If you have a
screenthat was compiled with
--enable-colors256, try exporting
TERM=screen-256coloras opposed to
Q: Notcurses looks like absolute crap in
mosh. A: Yeah it sure does. I'm not yet sure what's up.
Q: Why didn't you just use Sixel? A: Many terminal emulators don't support Sixel. Sixel doesn't work well with mouse selection. Sixel tends to be horribly inefficient, and has a limited color palette. With that said, both Sixel and the Kitty bitmap protocol are well-supported.
Q: I'm not seeing
NCKEY_RESIZEuntil I press some other key. A: You've almost certainly failed to mask
SIGWINCHin some thread, and that thread is receiving the signal instead of the thread which called
notcurses_getc_blocking(). As a result, the
poll()is not interrupted. Call
pthread_sigmask()before spawning any threads.
Q: Using the C++ wrapper, how can I ensure that the
NotCursesdestructor is run when I return from
main()? A: As noted in the C++ FAQ, wrap it in an artificial scope (this assumes your
NotCursesis scoped to
Q: How do I hide a plane I want to make visible later? A: In order of least to most performant: move it offscreen using
ncplane_move_yx(), move it underneath an opaque plane with
ncplane_move_below(), or move it off-pile with
Q: Why isn't there an
ncplane_box_yx()? Do you hate orthogonality, you dullard? A:
ncplane_box()and friends already have far too many arguments, you monster.
Q: Why doesn't Notcurses support 10- or 16-bit color? A: Notcurses supports 24 bits of color, spread across three eight-bit channels. You presumably mean 10-bit-per-channel color. Notcurses will support it when a terminal supports it.
Q: The name is dumb. A: That's not a question?
Q: I'm not finding qrcodegen on BSD, despite having installed
graphics/qr-code-generator. A: Try
cmake -DCMAKE_REQUIRED_INCLUDES=/usr/local/include. This is passed by
Q: Do you support musl? A: I try to! You'll need at least 1.20.
Q: I only seem to blit in ASCII, and/or can't emit Unicode beyond ASCII in general. A: Your
LANGenvironment variable is underdefined or incorrectly defined, or the necessary locale is not present on your machine (it is also possible that you explicitly supplied
NCOPTION_INHIBIT_SETLOCALE, but never called
setlocale(3), in which case don't do that).
Q: I pretty much always need an
ncplanewhen using a
nccell. Why doesn't the latter hold a pointer to the former? A: Besides the massive redundancy this would entail,
nccellneeds to remain as small as possible, and you almost always have the
ncplanehandy if you've got a reference to a valid
Q: I ran
notcurses-demo, but my table numbers don't match the Notcurses banner numbers, you charlatan. A:
notcurses-demorenders several frames beyond the actual demos.
Q: When my program exits, I don't have a cursor, or text is invisible, or colors are weird, ad nauseam. A: Ensure you're calling
ncdirect_stop()on all exit paths, including fatal signals.
Q: How can I use Direct Mode in conjunction with libreadline? A: Pass
ncdirect_init(), and ensure you do not pass
NCDIRECT_OPTION_NO_READLINE. If you'd like, set
rl_attempted_completion_functionprior to calling
ncdirect_init(). With that said, consider using a Notcurses
Q: Will there ever be Java wrappers? A: I should hope not. If you want a Java solution, try Autumn Lamonte's Jexer.
Q: Given that the glyph channel is initialized as transparent for a plane, shouldn't the foreground and background be initialized as transparent, also? A: Probably (they are instead initialized to default opaque). This would change some of the most longstanding behavior of Notcurses, though, so it isn't happening.
Q: Why does my right-to-left text appear left-to-right? A: Notcurses doesn't honor the BiDi state machine, and in fact forces left-to-right with BiDi codes. Likewise, ultra-wide glyphs will have interesting effects. ﷽!
Q: I get linker errors when statically linking. A: Are you linking all necessary libraries? Use
pkg-config --static --libs notcursesto discover them.
Q: Can I avoid manually exporting
COLORTERM=24biteverywhere? A: Sure. Add
sshd_configon the remote server. Yes, this will probably require root on the remote server. Don't blame me, man; I didn't do it.
Q: How about arbitrary image manipulation here functionality? A: I'm not going to beat ImageMagick et al. on image manipulation, but you can load an
ncvisualfrom RGBA memory using
“Our fine arts were developed, their types and uses were established, in times very different from the present, by men whose power of action upon things was insignificant in comparison with ours. But the amazing growth of our techniques, the adaptability and precision they have attained, the ideas and habits they are creating, make it a certainty that profound changes are impending in the ancient craft of the Beautiful.” —Paul Valéry