libConfuse: a small configuration file parser for C

A parser with a stated list of things it does not do

libConfuse is a configuration file parser library written in C, and its README is unusually clear about its scope. It supports sections and lists of values, along with other features such as single and double quoted strings, environment variable expansion, functions and nested include statements. Values can be strings, integers, floats, booleans and sections.

The goal is stated in the same paragraph, and it is a statement about what the project refuses. The goal is not to be the configuration file parser library with a gazillion of features. Instead, it aims to be easy to use and quick to integrate with your code.

That is a useful position for a C library, because the usual failure mode of a configuration parser is a large surface that every project wires differently. The feature list here is short enough to learn in an afternoon, and the type system is five types, which is a small contract to depend on.

The project was created by Martin Hedenfalk and released as open source software under the ISC licence. It was previously called libcfg, and the name was changed so as not to be confused with other similar libraries. It is developed and maintained on GitHub, with the issue tracker for bugs and feature requests.

The documentation is Doxygen, hosted on codedocs.xyz, and it is regenerated on every commit, with an API reference and a tutorial as the two entry points. The release history has a long gap in it: v3.2.2 in August 2018, v3.3 in June 2020, and v3.4 in August 2026, with the last push on 2026-10-15. So the current release is recent and the code underneath it has been around for a long time.

Building it with the usual autotools incantation

libConfuse employs the GNU configure and build system, so the build is the familiar one. The README insists on one thing first: ensure you download a versioned archive from the official releases page, rather than working from the branch.

The way to see the available build options is to unpack the tarball and ask configure:

$ tar xf confuse-3.2.2.tar.xz
$ cd confuse-3.2.2/
$ ./configure --help
...

And for most users, three commands configure, build and install the library to /usr/local:

$ ./configure && make -j9
...
$ sudo make install
$ sudo ldconfig

The ldconfig step is the one that trips people up. After installing a shared library into a default location, the dynamic linker cache needs refreshing, and without it a program that links against libconfuse fails at start-up with a missing shared object error rather than at build time.

Building from a GitHub checkout is different, because the configure script is generated rather than shipped. You run autogen.sh, and that needs autoconf, automake, libtool, gettext, autopoint and flex. The presence of flex in that list is a hint about the implementation, since flex is a lexer generator and the project is described as a lexer as well as a parser in its topic tags.

The documentation is an optional extra step that has to be built explicitly from its own directory, and it needs doxygen:

$ cd doc/
$ make documentation
...

The full installation instructions are in the INSTALL file, which the README notes is included in the versioned release archives, another small reason to use the archive rather than the branch.

The examples directory is the real feature documentation

The README points at four example files, and the repository carries a great many more, and between them they document the format better than the prose does.

The two the README names are simple.c with simple.conf, which show how to use the simple versions of the options, and cfgtest.c with test.conf, which show most of the features including lists and functions. The simple options are the point of that first pair, because a C library that makes you declare every option type, its default and its range before you can read a value is tedious to use, and the simple variants let you read a value without that ceremony.

The rest of the examples directory is a map of the format and the API. addsec.c deals with adding a section at runtime. cli.c is a command line driven configuration. deprecated.c and deprecated.conf show the handling of deprecated options, which is the kind of feature that matters in a long lived project. env.c and env.conf cover environment variable expansion, and ftp.conf and ftpconf.c cover the function support with a configuration that calls out to something else.

There are also inc.conf and nested.c for include statements, both nested and simple. parsebuf.c parses from a buffer rather than a file, which is what you want when the configuration arrives over a socket or is embedded in a binary. reread.c and reread.conf handle re-reading a file that changed on disk, and wincfgtest.c with wincfgtest.conf and wincfgtest.dev show the Windows side.

The examples directory therefore covers essentially every feature the library claims, which is the most efficient way to decide whether it does what you need.

A mature tree with a long dormant period

The repository layout shows a project that has been around for a long time and has been picked up again recently.

The build system is the old autotools style, with configure.ac, Makefile.am, an autogen.sh, an m4/ directory for the macros, and a libconfuse.pc.in that becomes the pkg-config file after configuration. There are several files of the kind that mature projects accumulate: an AUTHORS file, a ChangeLog.md, a HACKING.md, an INSTALL file, an indent.sh, which is a script for running the indentation over the source, and a libconfuse.spec.in, which is the template for an RPM package.

There is a po/ directory for translations, which is why gettext and autopoint are in the list of tools needed to bootstrap the build. There is a windows/ directory for the Microsoft toolchain, and a tests/ directory, and a doc/ directory with the Doxygen setup, and a .codedocs configuration for the hosted documentation.

The badges in the README point at a GitHub Actions build workflow and a Coverity scan for the project, so there is automated static analysis behind the current release, and the hosted documentation is regenerated on every commit, which means the API reference cannot drift from the code.

The gap between v3.3 in 2020 and v3.4 in 2026 is the story of the project's history, and it has two practical consequences. The first is that the recent release is young, so its own bug history is short, while the code it contains is old and has been exercised by many users. The second is that the issue tracker may contain a mixture of reports from both periods, and the question of which behaviour is intended is worth checking in the ChangeLog and the documentation rather than assuming the newest code is the intended design.

Where this fits, and where it does not

The honest summary is that libConfuse is a good fit for a C project that wants a small, readable configuration format and a low integration cost, and a poor fit for anything that wants a rich format or a validated schema.

The integration cost is genuinely low. A C project adds a header and links one library, with a pkg-config file to make the build line short, and the format is a simple indentation based syntax with sections and key and value pairs. There is no runtime configuration, no service and no background process, which is what makes it plausible on an embedded target, and the topic tags include embedded and cross platform for that reason.

The limitations follow from the same design. The type system is strings, integers, floats, booleans and sections, with no arrays of mixed types, no null, and no date or duration type. There is no schema in the documentation, so nothing validates a configuration file before your program reads it, and a mistyped key is a missing value rather than an error, unless the program checks for it. And the format is libConfuse's own, so a file written by it is not readable by other tools, and a file written for another tool is not readable by it.

That last point is the one to weigh against the alternatives. If your configuration has to be consumed by a shell script, by a container orchestrator, or by another program in another language, a bespoke format is a liability, and a format with an existing ecosystem is the better choice even if the parser is less pleasant to work with. libConfuse is at its best in the closed world of one binary and one file, which is also where the project's own examples live.

Editorial conclusion

libConfuse fits a C project that needs a configuration file with sections and lists and wants the whole thing to be a header, a library and a pkg-config file rather than a dependency tree, and it fits embedded targets where the parser has to be small. It is the wrong tool if you need a configuration format with a schema, with types beyond strings, integers, floats, booleans and sections, or with a structure that other tools already read, since nothing in the project offers validation. Before you adopt it, download a versioned archive rather than tracking the branch, read the examples directory to see which of the features you need are actually supported, and be aware that the release history is uneven, with v3.4 landing in 2026 after v3.3 in 2020, so the current release is young while the code base is old.

Frequently asked questions

Official sources

1. libconfuse/libconfuse on GitHub
2. License: ISC
3. Project website
4. README
5. Releases