NiGui: a cross-platform desktop GUI toolkit written in Nim

A Nim toolkit that sits on Win32 and GTK+ 3

NiGui is a cross-platform desktop GUI toolkit written in Nim, and it works by binding the native widget stack of the target platform rather than by drawing its own. The target platforms listed in the README are Windows through the Win32 API, Linux over GTK+ 3, and macOS over GTK+ 3 with native support planned.

That design gives every application the look and feel the user already knows. The README states that NiGui uses the native controls of the underlying platform, and that you can also build custom controls for special cases or a themed interface. The design goals section puts it plainly: a clean, beginner-friendly high-level API that is much less complex than the Win32 API, GTK+ or Qt, and the ability to profit from Nim features such as polymorphism that are awkward to express in C.

The dependency story is unusual and worth stating exactly. The README says the NiGui source code has no dependencies except Nim's standard library, that platform bindings are included, and that generated binaries include NiGui and do not need external libraries. On Linux and macOS the GTK+ 3 runtime is still a system requirement, so the no-dependency claim applies to the toolkit itself rather than to the whole stack your program sits on.

For a Nim developer, the pitch is that you can write a desktop application without learning a C-facing widget API or a Python-style binding layer.

Full abstraction and a layout manager of its own

Two of the four design goals in the README are worth examining on their own terms, because they determine what code you write.

Full abstraction is the first: NiGui applications are written once and can be compiled for different platforms, and the developer does not have to deal with platform-specific details. The second is the layout manager. NiGui has its own layout manager for automatic resizing and positioning of controls, exposed in the widget list as LayoutContainer.

A layout manager inside the toolkit is a meaningful difference from raw platform widgets. On Win32 and GTK+ 3, arranging controls means working with each system's container and geometry model, and the usual outcome is code with platform branches in it. NiGui takes that away, which is the point of the abstraction, but it also means you do not get the native container semantics, and you have to learn NiGui's rules instead of the ones you already know.

The rest of the goal list is about feel rather than structure. The toolkit is meant to be simple and elegant, it is meant to be powerful in the sense of using native controls, and it is meant to have minimal dependencies. The README also asks for custom controls and themed interfaces, which is where a toolkit like this typically needs its own drawing and event code.

Installing with Nimble and verifying with the bundled examples

The shortest install path uses Nimble, the Nim package manager. The README gives the command as a single line:

$ nimble install nigui

Verification is done by compiling and running one of the included example programs, which is what the README suggests under how to verify the installation. The examples directory in the repository is large enough to act as a de facto tutorial: example_01_basic_app, example_02_controls, example_03_layout_container, example_04_msgboxes, example_05_handle_window_close, example_06_keyboard_events, example_08_timers, example_09_font_size, example_10_drawing, example_11_image_processing_cli, example_12_file_dialogs, example_13_fixed_layout, example_14_container_scrolling, example_15_threading, example_30_custom_button, example_31_custom_widget, plus example_90_widget_error and example_91_unhandled_exception.

The numbering is informative on its own. The high-numbered examples cover the edges: a custom button, a fully custom widget, and two that deliberately exercise error paths. There is also a configuration file, examples/config.nims, and an examples/nim.cfg.

If you prefer to build from a checkout, the manual route is to clone the repository and add the source path to one of your Nim configuration files:

--path:"<path_to_nigui>/src"

That is the whole manual install. The repository layout is small, with src holding the toolkit, examples the samples, nigui.nimble the package definition, and faq.md and license.md at the top level.

Platform switches: --app:gui, forceGtk and GTK+ on macOS

Three configuration lines decide how the toolkit behaves on a given machine, and the README is specific about each.

To suppress the command line window on Windows, add this line to your Nim configuration:

--app:gui

To compile a Windows binary that uses GTK rather than the native Win32 path, add:

-d:forceGtk

That second switch exists because the platform selection on Windows is otherwise automatic, and the ability to force the GTK backend is what makes it possible to test the Linux code path, and the GTK dependency, from a Windows machine.

On macOS, GTK+ 3 is installed with homebrew:

brew install gtk+3

The target platform list marks macOS as GTK+ 3 with native support planned, and macOS support also appears in the contributing section as a task the project would like help with. The planned features list adds more widgets to the same bucket.

One more piece of configuration sits in the repository rather than in the README instructions: examples/config.nims. Applications built alongside those examples will pick up the same flags, which is a convenient way to see how the switches are actually used in a project.

The widget list that works and the two gaps still open

The README is unusually candid about its state. It says NiGui is currently work in progress, that very basic things work, and that many things are missing.

What is listed as working: Window, Button, Label, TextBox and TextArea, the LayoutContainer with its own layout manager, timers, message boxes and file dialogs, custom controls including scrolling, and drawing and image processing.

What is listed as work in progress: event handling and documentation. Both of these are load-bearing for anything beyond a demo. Event handling sits underneath every user interaction, and the fact that the project lists it as incomplete rather than finished is the single most important line in the README for an adopter. Documentation is the other gap, and the repository compensates with a faq.md file at the top level and a pile of numbered examples, which is a workable but informal substitute.

The planned column is macOS support and more widgets. The project also asks contributors to test programs under different Windows versions or Linux distributions, which is a hint that platform-specific behaviour is where the roughness is.

The show cases give a sense of scale. NiCalc is a simple calculator and Gravitate is a tilefall-like game, both linked from the README.

Threading, custom widgets and the shape of the source tree

Two example files point at features that matter for real applications. example_15_threading covers threading, and example_31_custom_widget, alongside example_30_custom_button, covers the extension path where you draw your own control rather than using a native one. example_90_widget_error and example_91_unhandled_exception sit alongside them, which suggests the project has thought about failure handling inside the widget system.

The examples also cover the less glamorous paths that a GUI toolkit always needs: file dialogs in example_12, keyboard events in example_06, timers in example_08, font size handling in example_09, container scrolling in example_14, a fixed layout in example_13, and an image processing command line variant in example_11.

At the repository level, the tree is deliberately small. src holds the implementation, examples the sample programs, .github the workflow configuration, and nigui.nimble the package manifest that the Nimble install uses. There is no separate C library, no vendored widget set and no build script beyond what Nim itself does.

That minimalism is the reason the dependency claim holds. It also means the toolkit is one maintainer's design, and the ownership contact given in the README is a personal organisation page rather than a foundation project.

How NiGui differs from binding GTK or Qt yourself

The realistic alternative for a Nim developer with a desktop application is not another Nim toolkit but writing the binding layer yourself, or using a general purpose framework. NiGui's own README compares itself to the Win32 API, GTK+ and Qt and claims to be much less complex than any of them, so that is the comparison to examine.

The difference is one of abstraction level. Binding GTK+ 3 or Qt directly from Nim gives you the full widget vocabulary and the platform's own layout containers, but every window you write is tied to that toolkit's API and its installation requirements, and the code is not portable to a different platform stack. NiGui instead exposes one API that covers Win32 and GTK+ 3, ships its own layout manager so you do not learn two container models, and compiles to a binary that carries the toolkit with it.

The trade-off is direct. You give up the completeness of the underlying toolkit and work against an API the project itself calls work in progress, with event handling and documentation unfinished and macOS only planned. For a calculator or an internal tool, that trade is worth it. For an application that needs rich data grids, complex list editing or a mature event system, binding the platform toolkit directly is the sounder choice.

Editorial conclusion

Use NiGui when you are writing a small Nim desktop tool that should look native on Windows and Linux, or when you want a GUI without pulling in a heavyweight framework, since the source depends only on the Nim standard library and the platform bindings ship with it. Do not choose it for a project that needs a mature event model or thorough documentation, because the README lists event handling and documentation as work in progress, and macOS support is only planned. Before starting, verify the GTK+ 3 runtime is present on Linux, decide whether you want the bundled examples as your reference, and pin your dependency to the v0.2.8 release from 2024-02-28 given that the last push to the repository was on 2026-04-07.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. simonkrauter/NiGui on GitHub