toml++ for C++: Complete Guide with Examples

1. What It Is and Why You Need It

TOML (Tom's Obvious Minimal Language) is a configuration file format created as an alternative to INI, YAML, and JSON. It is designed to be maximally human-readable, map unambiguously to hash tables, and be simple to parse. Unlike YAML, TOML does not allow ambiguities (e.g., with indentation or data types), and unlike JSON, it does not require quotes for keys and supports comments.

toml++ (also known as tomlplusplus) is a modern, header-only library for parsing and generating TOML files in C++17 and above. It requires no compilation: you simply include the header file and get full functionality. This makes it an ideal choice for projects where ease of integration, performance, and strong typing are important.

Why use toml++? First, it provides full support for the TOML v1.0 specification, including inline tables, arrays of tables, dates, times, and local dates. Second, it is written with a focus on type safety: you get not a raw JSON-like object, but strictly typed values (std::string, int64_t, double, bool, toml::date, etc.). Third, it is incredibly fast and has minimal dependencies (only the C++17 standard library).

2. Installation

toml++ is a header-only library. This means you do not need to compile it separately. Simply copy the header files into your project and include them.

Method 1: Vcpkg (recommended for Windows and Linux)

# Installation via vcpkg\nvcpkg install tomlplusplus\n\n# Linking in CMakeLists.txt\nfind_package(tomlplusplus CONFIG REQUIRED)\ntarget_link_libraries(my_project PRIVATE tomlplusplus::tomlplusplus)\n

Method 2: Conan

# Installation via Conan\nconan install tomlplusplus/3.4.0@\n\n# In conanfile.txt\n[requires]\ntomlplusplus/3.4.0\n\n[generators]\nCMakeDeps\n

Method 3: Manual Installation (simplest)

# Download the latest release from GitHub\nwget https://github.com/marzer/tomlplusplus/archive/refs/tags/v3.4.0.tar.gz\ntar -xzf v3.4.0.tar.gz\n\n# Copy the include/toml++ folder to your project\ncp -r tomlplusplus-3.4.0/include/toml++ /path/to/your/project/include/\n\n# In your code, simply include:\n#include <toml++/toml.h>\n

Method 4: CMake FetchContent (for CMake projects)

include(FetchContent)\nFetchContent_Declare(\n    tomlplusplus\n    GIT_REPOSITORY https://github.com/marzer/tomlplusplus.git\n    GIT_TAG v3.4.0\n)\nFetchContent_MakeAvailable(tomlplusplus)\n\ntarget_link_libraries(my_project PRIVATE tomlplusplus::tomlplusplus)\n

3. Quick Start — Minimal Working Example

Create a file config.toml:

# config.toml\ntitle = "Example configuration"\n\n[server]\nhost = "localhost"\nport = 8080\ndebug = true\n\n[database]\nname = "mydb"\nuser = "admin"\npassword = "secret123"\n

Now write C++ code to read it:

#include <toml++/toml.h>\n#include <iostream>\n#include <filesystem>\n\nint main() {\n    // 1. Parse the file\n    auto config = toml::parse_file("config.toml");\n\n    // 2. Read simple values\n    std::string title = config["title"].value_or("default");\n    std::cout << "Title: " << title << std::endl;\n\n    // 3. Read nested tables\n    auto server = config["server"];\n    std::string host = server["host"].value_or("localhost");\n    int port = server["port"].value_or(3000);\n