|2 weeks ago
|11 months ago
|3 years ago
|1 year ago
|2 years ago
|10 months ago
|4 weeks ago
|1 year ago
|2 months ago
|1 year ago
|2 years ago
|2 years ago
|3 months ago
|3 years ago
|2 weeks ago
|11 months ago
|1 year ago
|10 months ago
|11 months ago
|2 weeks ago
Notcurses: blingful TUIs and character graphics
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.
for more information, see dankwiki and the man pages. in addition, there is Doxygen output. To subscribe to the mailing list, send an email to email@example.com (the email contents don't matter). i wrote a coherent guidebook, which is available for free download (or paperback purchase).
If you're running Notcurses applications in a Docker, please consult "Environment notes" below.
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. 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.
Portable support for bitmapped graphics, using Sixel, Kitty, and even the Linux framebuffer console.
Support for unambiguous keyboard protocols.
"TUI mode" facilitates high-performance, non-scrolling, full-screen applications. "CLI mode" supports scrolling output for shell utilities, but with the full power of Notcurses.
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 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!
- (build) CMake 3.14.0+ and a C11 compiler
- (OPTIONAL) (OpenImageIO, testing, C++ bindings): A C++17 compiler
- (build+runtime) From NCURSES: terminfo 6.1+
- (build+runtime) GNU libunistring 0.9.10+
- (OPTIONAL) (build+runtime) libgpm 1.20+
- (OPTIONAL) (build+runtime) From QR-Code-generator: libqrcodegen 1.5.0+
- (OPTIONAL) (build+runtime) From FFmpeg: libswscale 5.0+, libavformat 57.0+, libavutil 56.0+, libavdevice 57.0+
- (OPTIONAL) (build+runtime) OpenImageIO 2.15.0+, requires C++
- (OPTIONAL) (testing) Doctest 2.3.5+
- (OPTIONAL) (documentation) pandoc 1.19.2+
- (OPTIONAL) (python bindings): Python 3.7+, CFFI 1.13.2+, pypandoc 1.5+
- (runtime) Linux 2.6+, FreeBSD 11+, DragonFly BSD 5.9+, Windows 10 v1093+, or macOS 11.4+
More information on building and installation is available in INSTALL.md.
If you wish to use a language other than C to work with Notcurses, numerous wrappers are available. Several are included in this repository, while others are external.
|Marek Habersack, nick black
|Michael S. Bradley, Jr.
|José Luis Cruz
Nine executables 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-info: detect and print terminal capabilities/diagnostics
notcurses-input: decode and print keypresses
notcurses-tester: unit testing
tfman: a swank manual browser
notcurses-demo from a checkout, provide the
data directory via
-p argument. Demos requiring data files will otherwise abort. The base
delay used in
notcurses-demo can 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-tester likewise 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
- Per-release News for packagers, developers, and users.
TERMenvironment variable and various terminal emulators.
- Notes on contributing and hacking.
- There's a semi-complete reference guide.
- A list of other TUI libraries.
- Abbreviated history and thanks.
- Differences from Curses and adapting Curses programs.
If you (understandably) want to avoid the large Pandoc stack, but still enjoy manual pages, I publish a tarball with generated man/XHTML along with each release. Download it, and install the contents as you deem fit.
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.
Notcurses queries the terminal on startup, enabling some advanced features based on the determined terminal (and even version). Basic capabilities, however, are taken from Terminfo. So if you have, say, Kitty, but
TERM=vt100, you're going to be able to draw RGBA bitmap graphics (despite such things being but a dream for a VT100), but unable to use the alternate screen (despite it being supported by every Kitty version). So
TERMand an up-to-date Terminfo database remain important.
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).
If your terminal supports 3x8bit RGB color via
setbf(most modern terminals), but exports neither the
Tcterminfo capability, you can export the
COLORTERMenvironment variable as
24bit. Note that some terminals accept a 24-bit specification, but map it down to fewer colors. RGB is unconditionally enabled whenever most modern terminals are identified.
Glyph width, and indeed whether a glyph can be displayed at all, is dependent
in part on the font configuration. Ideally, your font configuration has a
glyph for every Unicode EGC, and each glyph's width matches up with the POSIX
wcswidth() result for the EGC. If this is not the case, you'll
likely get blanks or <20> (U+FFFD, REPLACEMENT CHARACTER) for missing characters,
and subsequent characters on the line may be misplaced.
It is worth knowing that several terminals draw the block characters directly,
rather than loading them from a font. This is generally desirable. Quadrants
and sextants are not the place to demonstrate your design virtuosity. To
inspect your environment's rendering of drawing characters, run
notcurses-info. The desired output ought look something like this:
If things break or seem otherwise lackluster, please consult the
Environment Notes section! You need correct
LANG definitions, and might want
Can I use Notcurses in my closed-source program?Notcurses is licensed under Apache2, a demonstration that I have transcended your petty world of material goods, fiat currencies, and closed sources. Implement Microsoft Bob in it. Charge rubes for it. Put it in your ballistic missiles so that you have a nice LED display of said missile's speed and projected yield; right before impact, scroll "FUCK YOU" in all the world's languages, and close it out with a smart palette fade. Carve the compiled objects onto bricks and mail them to Richard Stallman, taunting him through a bullhorn as you do so.
Can I write a CLI program (scrolling, fits in with the shell, etc.) with Notcurses?Yes! Use the
NCOPTION_CLI_MODE flag (an alias for several
real flags; see
for more information). You still must explicitly render.
Can I have Notcurses without this huge multimedia stack?Again yes! Build with
Can I build this individual Notcurses program without aforementioned multimedia stack?Almost unbelievably, yes! Use
ncdirect_core_init() in place of
ncdirect_init(), and link with
Your application will likely start a few milliseconds faster;
more importantly, it will link against minimal Notcurses installations.
We're paying by the electron, and have no C++ compiler. Can we still enjoy Notcurses goodness?Some of it! You won't be able to build several executables, nor the NCPP C++ wrappers, nor can you build with the OpenImageIO multimedia backend (OIIO ships C++ headers). You'll be able to build the main library, though, as well as
notcurses-demo (and maybe a few other programs).
Do I want ffmpeg or OpenImageIO?While OpenImageIO is a superb library for dealing with single-frame images, its video support is less than perfect (blame me; I've been promising Larry I'd rewrite it for several months), and in any case implemented atop...ffmpeg. ffmpeg is the preferred multimedia backend.
Does it work with hardware terminals?With the correct
TERM value, many hardware terminals are
supported. In general, if the terminfo database entry indicates mandatory
delays, Notcurses will not currently support that terminal properly. It's
known that Notcurses can drive the VT320 and VT340, including Sixel graphics
on the latter.
What happens if I try blitting bitmap graphics on a terminal which doesn't support them?Notcurses will not make use of bitmap protocols unless the terminal positively indicates support for them, even if
NCBLIT_PIXEL has been
requested. Likewise, sextants (
NCBLIT_3x2) won't be used without
Unicode 13 support, etc.
ncvisual_blit() will use the best blitter
NCVISUAL_OPTION_NODEGRADE is provided (in
which case it will fail).
Notcurses looks like absolute crap in
screen doesn't support RGB colors (at least as of 4.08.00);
if you have
COLORTERM defined, you'll have a bad time.
If you have a
screen that was compiled with
--enable-colors256, try exporting
TERM=screen-256color as opposed to
Notcurses looks like absolute crap in
Yeah it sure does. I'm not yet sure what's up.
Notcurses looks like absolute crap in Windows Terminal.Go to Language Setting, click "Administrative language settings", click "Change system locale", and check the "Beta: Use Unicode UTF-8 for worldwide language support" option. Restart the computer. That ought help a little bit. Try playing with fonts—Cascadia Code and Cascadia Mono both seem to work well (quadrants and Braille both work), whereas Consolas and Courier New both have definite problems.
I'm getting strange and/or duplicate inputs in Kitty/foot.Notcurses supports Kitty's powerful keyboard protocol, which includes things like key release events and modifier keypresses by themselves. This means, among other things, that a program in these terminals will usually immediately get an
event, and each keypress will typically result in at least two inputs.
Why didn't you just render everything to bitmaps?That's not a TUI; it's a slow and inflexible GUI. Many terminal emulators don't support bitmaps. They doesn't work well with mouse selection. Sixels have a limited color palette. With that said, both Sixel and the Kitty bitmap protocol are well-supported.
My multithreaded program doesn't see
You've almost certainly failed to mask
I press some other key.
SIGWINCH in some thread,
and that thread is receiving the signal instead of the thread which called
notcurses_getc_blocking(). As a result, the
is not interrupted. Call
pthread_sigmask() before spawning any
Using the C++ wrapper, how can I ensure that the
As noted in the
C++ FAQ, wrap it in an artificial scope (this assumes your
destructor is run when I return from
NotCurses is scoped to
How do I hide a plane I want to make visible later?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
Why isn't there an
ncplane_box_yx()? Do you hate
orthogonality, you dullard?
ncplane_box() and friends
already have far too many arguments, you monster.
Why doesn't Notcurses support 10- or 16-bit color?Notcurses supports 24 bits of color, spread across three eight-bit channels. You presumably mean 10-bit-per-channel color. I needed those six bits for other things. When terminals support it, Notcurses might support it.
The name is dumb.That's not a question?
I'm not finding qrcodegen on BSD, despite having installed
This is passed by
Do you support musl?I try to! You'll need at least 1.20.
I only seem to blit in ASCII, and/or can't emit Unicode beyond ASCII in general.Your
LANG environment variable is underdefined or incorrectly
defined, or the necessary locale is not present on your machine (it is also
possible that you explicitly supplied
but never called
setlocale(3), in which case don't do that).
I pretty much always need an
Besides the massive redundancy this would entail,
ncplane when using a
nccell. Why doesn't the latter hold a pointer to the former?
nccell needs to
remain as small as possible, and you almost always have the
handy if you've got a reference to a valid
I ran my Notcurses program under
Yeah, the NCURSES Terminfo leaks memory unless compiled a special,
non-standard way (see the NCURSES FAQ). It shouldn't be a substantial amount;
you're advised not to worry overmuch about it.
it shows memory leaks from
libtinfo.so, what's up with that?
notcurses-demo, but my table numbers don't match
the Notcurses banner numbers, you charlatan.
notcurses-demo renders several frames beyond the actual demos.
When my program exits, I don't have a cursor, or text is invisible, or colors are weird, ad nauseam.Ensure you're calling
on all exit paths, including fatal signals (note that, by default, Notcurses
installs handlers for most fatal signals to do exactly this).
How can I use Direct Mode in conjunction with libreadline?You can't anymore (you could up until 2.4.1, but the new input system is fundamentally incompatible with it).
ncdirect_readline() still exists,
though, and now actually works even without libreadline, though it is of
course not exactly libreadline. In any case, you'd probably be better off
using CLI mode with a
So is Direct Mode deprecated or what?It is not currently deprecated, and definitely receives bugfixes. You are probably better served using CLI mode (see above), which came about somewhat late in Notcurses development (the 2.3.x series), but is superior to Direct Mode in pretty much every way. The only reason to use Direct Mode is if you're going to have other programs junking up your display.
Direct Mode sounds fast! Since it's, like, direct.Direct mode is substantially slower than rendered mode. Rendered mode assumes it knows what's on the screen, and uses this information to generate optimized sequences of escapes and glyphs. Direct mode writes everything it's told to write. It is furthermore far less capable—all widgets etc. are available only to rendered mode, and will definitely not be extended to Direct Mode.
Will there ever be Java wrappers?I should hope not. If you want a Java solution, try @klamonte's Jexer. Autumn's a good woman, and thorough. We seem to have neatly partitioned the language space.
Given that the glyph channel is initialized as transparent for a plane, shouldn't the foreground and background be initialized as transparent, also?Probably (they are instead by default initialized to opaque). This would change some of the most longstanding behavior of Notcurses, though, so it isn't happening.
I get linker errors when statically linking.Are you linking all necessary libraries? Use
pkg-config --static --libs notcurses
--libs notcurses-core) to discover them.
Notcurses exits immediately in MSYS2/Cygwin.Notcurses requires the Windows ConPTY layer. This is available in Cygwin by default since 3.2.0, but is disabled by default in MSYS. Launch
arguments, or export
MSYS=enable_pcon before launching it.
Can I avoid manually exporting
SendEnv COLORTERM to
AcceptEnv COLORTERM to
sshd_config on the remote
server. Yes, this will probably require root on the remote server.
Don't blame me, man; I didn't do it.
How about arbitrary image manipulation here functionality?I'm not going to beat ImageMagick et al. on image manipulation, but you can load an
ncvisual from RGBA memory using
My program locks up during initialization.Notcurses interrogates the terminal. If the terminal doesn't reply to standard interrogations, file a Notcurses bug, send upstream a patch, or use a different terminal. No known terminal emulators exhibit this behavior.
How can I draw a large plane, and only make a portion of it visible?The simplest way is probably to create a plane of the same dimensions immediately above the plane, and keep a region of it transparent, and the rest opaque. If you want the visible area to stay in the same place on the display, but the portion being seen to change, try making a plane twice as large in each dimension as the original plane. Make the desired area transparent, and the rest opaque. Now move the original plane behind this plane so that the desired area lines up with the “hole”.
It would consume a precious bit. You can use
to correctly invert fore- and background colors.
How do I mix Rendered and Direct mode?You really don't want to. You can stream a subprocess to a plane with the
How can I clear the screen on startup in Rendered mode when not using the alternate screen?Call
Why do the stats show more Linux framebuffer bitmap bytes written than total bytes written to the terminal? And why don't Linux console graphics work when I ssh?Linux framebuffer graphics aren't implemented via terminal writes, but rather writes directly into a memory map. This memory map isn't available on remote machines, and these writes aren't tracked by the standard statistics.
What is the possessive form of Notcurses?Notcurses'. I cite Garner's Modern English Usage in its third edition: "POSSESSIVES. A. Singular Possessives.…Biblical and Classical names that end with a /zəs/ or /eez/ sound take only the apostrophe." Some ask: is Notcurses then Biblical, or is it Classical? Truly, it is both.
I just want to display a bitmap on my terminal. Your library is complex and stupid. You are simple and stupid.If you're willing to call a binary, use ncplayer to put an image, with desired scaling, anywhere on the screen and call it a day. Otherwise, call notcurses_init(), ncvisual_from_file(), ncvisual_blit(), notcurses_render(), and notcurses_stop(). It's not too tough. And thanks—your thoughtful comments and appreciative tone are why I work on Free Software.
- BiDi in Terminal Emulators
- The Xterm FAQ
- The NCURSES FAQ
- ECMA-35 Character Code Structure and Extension Techniques (ISO/IEC 2022)
- ECMA-43 8-bit Coded Character Set Structure and Rules
- ECMA-48 Control Functions for Coded Character Sets (ISO/IEC 6429)
- Unicode 14.0 Full Emoji List
- Unicode Standard Annex #29 Text Segmentation
- Unicode Standard Annex #15 Normalization Forms
- mintty tips
- The TTY demystified
- Dark Corners of Unicode
- UTF-8 Decoder Capability and Stress Test
- Emoji: how do you get from U+1F355 to 🍕?
- Glyph Hell: An introduction to glyphs, as used and defined in the FreeType engine
- Text Rendering Hates You
- Use the UTF-8 code page
- My wiki's Sixel page and Kitty's extensions.
- Linux man pages: console_codes(4), termios(3), ioctl_tty(2), ioctl_console(2)
- The Microsoft Windows Console Reference
- NCURSES man pages: terminfo(5), user_caps(5)
“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