nativefiledialog-extended: Native File Dialogs Without a GUI Toolkit

Why Not Link Qt or wxWidgets Just for a File Dialog

The pitch is narrow. Native File Dialog Extended is a small C library that portably invokes native file open, folder select and file save dialogs, so you write the dialog code once and get native dialogs on every supported platform. The motivation is stated in the first paragraph: you avoid linking large dependencies such as wxWidgets and Qt.

That matters most in the categories the library's own feature list cares about. It is stated to work alongside SDL, GLFW and ImGui on all platforms, which are the graphics and input layers a game or an immediate mode tool already carries. A tool that otherwise links nothing but a windowing library can show the operating system's own dialog without taking on a widget toolkit as well.

The library is plain C with a lean API and a static library build, and the feature list states that no C++ or Objective-C runtime is needed. The C++ side is optional: a wrapper with unique_ptr auto-freeing semantics and optional parameters exists for projects that want it. The licence is Zlib, and the list ends with the point that matters to many reviewers, no third party dependencies.

Two API Families: UTF-8 and Native Character Set

Every function in the API comes in two spellings. The U8 and u8 forms use UTF-8 characters with the char type, and the README says that is what most consumers probably want. The N and n forms use the native character type, which is wchar_t on Windows and char on the other platforms.

The Windows split exists because the native character set there is UTF-16, and the library supports both so that a Windows application can use the wide API where it needs to interoperate with the platform, and the UTF-8 API everywhere else. The stated promise is consistent UTF-8 support on all platforms, with the native variant as the escape hatch.

The calling convention is a result code plus an out parameter, with the extended argument struct carrying the options. A minimal open dialog looks like this:

#include <nfd.h>

    NFD_Init();

    nfdu8char_t *outPath;
    nfdu8filteritem_t filters[2] = { { "Source code", "c,cpp,cc" }, { "Headers", "h,hpp" } };
    nfdopendialogu8args_t args = {0};
    args.filterList = filters;
    args.filterCount = 2;
    nfdresult_t result = NFD_OpenDialogU8_With(&outPath, &args);

The result is checked against NFD_OKAY, NFD_CANCEL and an error branch that calls NFD_GetError, and the returned path is released with NFD_FreePathU8. The full list of fields on the args struct is documented in the All Options section of the README.

Friendly Filter Names Are the Reason the API Broke

The library is based on Michael Labbe's Native File Dialog, and the README is open about the divergence. The friendly names feature is described as the primary reason for breaking API compatibility with that library, and it adds that this library probably will never be merged with it.

The feature itself is small but user visible. Where a platform supports it, a filter is written with a label and its patterns, so the dropdown reads C/C++ Source files (*.c;*.cpp) rather than the bare (*.c;*.cpp). On platforms that cannot do friendly names, the label is simply not shown.

The other additions listed against the original are automatic file extension appending on platforms where users expect it, a default file name such as Untitled.c, a default folder path, a parent window handle so the dialog stays on top of the application window, native character set support on Windows, xdg-desktop-portal support on Linux, multiple folder selection, decoupled initialisation and de-initialisation of the platform library, a modern CMake build, and the optional C++ wrapper. The README also notes significant code refactoring, especially in the Windows implementation.

Linux Decides Between GTK and the Portal at Build Time

On Linux the library has two backends and the choice is made when you build, not at runtime. GTK is used by default, and the xdg-desktop-portal backend is enabled with a compile option, which opens the native file chooser of the running desktop environment. The Flatpak desktop portal is the case the README highlights, since inside a Flatpak sandbox the portal is the route to the host's file chooser.

The Wayland detail is easy to miss and it breaks builds. On Linux, with Wayland support being the default, the project depends on the Wayland protocols as a git submodule, so it has to be checked out before you configure:

git submodule update --init

The repository layout supports that arrangement, with a .gitmodules file at the root and a 3ps/ directory for third party sources.

Windows is handled with the modern Vista IFileDialog interface rather than the older shell APIs, and the screenshots in the repository cover Windows 10, macOS and GTK3 on Ubuntu 20.04, in both light and dark appearances, which is a useful check on how the three backends actually look side by side.

Init and Quit Are Decoupled So the Application Can Own the Lifetime

One design decision deserves attention because it changes how a library like this behaves inside a larger program. Initialisation and de-initialisation of the platform library, which means COM on Windows, GTK on Linux with the GTK backend and D-Bus for the Linux portal, are decoupled from the dialog functions themselves. The application chooses when to initialise and when to de-initialise.

In practice this is what lets a tool that already owns a COM apartment or a GTK initialisation sequence use this library without fighting over the lifetime of those subsystems. The basic usage sample still shows the simple pattern of calling NFD_Init at the start and NFD_Quit at the end, but the decoupling means you are not forced into it.

The other capability on the list is multiple selection, supported for the file open and folder select dialogs, and multiple folder selection is called out as one of the features added over the original library. Returning several paths at once is where the memory handling matters, since each path has to be freed, and the API keeps that explicit through the NFD_FreePath style calls.

Two Ways to Build: As a CMake Subproject or a Standalone Library

For a project that already uses CMake, the integration is a subdirectory and a link line:

add_subdirectory(path/to/nativefiledialog-extended)
target_link_libraries(MyProgram PRIVATE nfd)

When it is included as a subproject, the sample programs are not built and the install target is disabled by default, and two options flip that. -DNFD_BUILD_TESTS=ON builds the sample programs and -DNFD_INSTALL=ON enables the install target.

Building the standalone static library is a normal out-of-source CMake run, and the README gives the commands for both toolchains. For GCC and Clang:

mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build .

For MSVC the difference is that the build type is a configuration rather than a define, using cmake .. followed by cmake --build . --config Release. As a standalone build the samples are built and the install target is enabled by default, and the same two options, set to OFF, turn them off again. The CI build file in the repository is pointed at as the reference for real example commands.

Release Cadence and the Bindings Wiki

The project is moving quickly. The recent tags are v1.4.1 from 2026-10-02, v1.4.0 from 2026-09-17 and v1.3.0 from 2026-01-06, so the 1.4 line has seen two releases within about two weeks, and the repository is not archived with the last push on 2026-10-02.

A gap of roughly eight months between 1.3.0 and 1.4.0 followed by two releases in about two weeks is a pattern worth watching, since the minor version bump is where the API can move. The README lists the breaks in compatibility with the original library as deliberate and permanent, and the additions in each line accumulate, so a project that pins an older tag should treat an upgrade as an API review rather than a routine bump.

The wiki is where the ecosystem information sits. The README says the wiki keeps track of known language bindings and known popular projects that depend on the library, which is the fastest way to see whether the C++ wrapper and the API shape are already proven in the kind of project you are building. The repository itself carries a.clang-format file, a CMakeLists.txt, the src/ directory with the implementation, a test/ directory, and a screens/ directory with the dialog captures.

Editorial conclusion

nativefiledialog-extended fits a game, tool or editor that needs a native file picker and refuses to take on a GUI toolkit for it, and it will not fit a codebase that needs the original Native File Dialog API unchanged, since the friendly filter names deliberately break source compatibility. Before adopting it, decide whether the Linux backend will be GTK or the xdg-desktop-portal, because that choice is fixed at build time with -DNFD_PORTAL=ON, and check the Wayland submodule step, since a Linux build with Wayland support needs git submodule update --init. The library is Zlib licensed, the newest release is v1.4.1 from 2026-10-02, and the last push was on 2026-10-02.

Frequently asked questions

Official sources

1. btzy/nativefiledialog-extended on GitHub
2. Issues
3. License: Zlib
4. README
5. Releases