Header-only TOML config file parser and serializer for C++17 (and later!).
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Mark Gillard 8e669aa699 release v3.0.1 2 weeks ago
.circleci fixed false-positive warning on clang 13 1 month ago
.github fixed date parsing when the year has a leading zero (closes #130) 3 weeks ago
cmake add cpp.hint to cmake install 8 months ago
docs release v3.0.1 2 weeks ago
examples fixed treating non-ASCII horizontal whitespace as valid (closes #135) 2 weeks ago
external fixed inconsistent error messages for overlong ints/floats (closes #133) 3 weeks ago
include/toml++ release v3.0.1 2 weeks ago
tests release v3.0.1 2 weeks ago
toml-test fixed inconsistent error messages for overlong ints/floats (closes #133) 3 weeks ago
tools fixed inconsistent error messages for overlong ints/floats (closes #133) 3 weeks ago
.clang-format fixed inconsistent error messages for overlong ints/floats (closes #133) 3 weeks ago
.editorconfig documentation fixes, redux 9 months ago
.gitattributes added clang's enum annotation attributes to all enums 3 months ago
.gitignore restructuring and minor refactoring 9 months ago
.gitmodules fixed some incorrect handling of vertical whitespace when printing TOML to streams 3 weeks ago
.runsettings minor config fixes [skip ci] 8 months ago
CHANGELOG.md release v3.0.1 2 weeks ago
CMakeLists.txt release v3.0.1 2 weeks ago
CODE_OF_CONDUCT.md Added code of conduct [skip ci] 2 years ago
CONTRIBUTING.md fixed some incorrect handling of vertical whitespace when printing TOML to streams 3 weeks ago
LICENSE update copyright year [skip ci] 1 year ago
README.md release v3.0.1 2 weeks ago
cpp.hint fixed inconsistent error messages for overlong ints/floats (closes #133) 3 weeks ago
meson.build release v3.0.1 2 weeks ago
meson_options.txt fixed some incorrect handling of vertical whitespace when printing TOML to streams 3 weeks ago
toml++.natvis added `toml::key` (closes #82) 3 months ago
toml++.props fixed segfault JSON-formatting a failed parse_result (closes #96) 9 months ago
toml++.sln added regression test to detect ODR violations 2 weeks ago
toml++.vcxproj fixed inconsistent error messages for overlong ints/floats (closes #133) 3 weeks ago
toml++.vcxproj.filters fixed inconsistent error messages for overlong ints/floats (closes #133) 3 weeks ago
toml.hpp release v3.0.1 2 weeks ago


Releases C++17 C++20 TOML MIT license CircleCI Mentioned in Awesome C++

toml++ homepage

️ This README is fine, but the toml++ homepage is better.

Library features

  • Header-only
  • Supports the latest TOML release (v1.0.0), plus optional support for some unreleased TOML language features
  • C++17 (plus some C++20 features where available, e.g. experimental support for char8_t strings)
  • Proper UTF-8 handling (incl. BOM)
  • Works with or without exceptions
  • Doesn't require RTTI
  • Support for serializing to JSON and YAML
  • Tested on Clang (6+), GCC (7+) and MSVC (VS2019, VS2022)
  • Tested on x64, x86 and ARM

Basic usage

ℹ️ The following example favours brevity. If you'd prefer full API documentation and lots of specific code snippets instead, visit the project homepage

Given a TOML file configuration.toml containing the following:

name = "toml++"
authors = ["Mark Gillard <mark.gillard@outlook.com.au>"]

cpp = 17

Reading it in C++ is easy with toml++:

#include <toml.hpp>

auto config = toml::parse_file( "configuration.toml" );

// get key-value pairs
std::string_view library_name = config["library"]["name"].value_or(""sv);
std::string_view library_author = config["library"]["authors"][0].value_or(""sv);
int64_t depends_on_cpp_version = config["dependencies"]["cpp"].value_or(0);

// modify the data
config.insert_or_assign("alternatives", toml::array{

// iterate & visit over the data
for (auto&& [k, v] : config)
    v.visit([](auto& node) noexcept
        std::cout << node << "\n";
        if constexpr (toml::is_string<decltype(node)>)

// re-serialize as TOML
std::cout << config << "\n";

// re-serialize as JSON
std::cout << toml::json_formatter{ config } << "\n";

// re-serialize as YAML
std::cout << toml::yaml_formatter{ config } << "\n";

You'll find some more code examples in the examples directory, and plenty more as part of the API documentation.

Adding toml++ to your project

toml++ comes in two flavours: Single-header and Regular. The API is the same for both.

🍦️ Single-header flavour

  1. Drop toml.hpp wherever you like in your source tree
  2. There is no step two

🍨️ Regular flavour

  1. Add tomlplusplus/include to your include paths
  2. #include <toml++/toml.h>


Add tomlplusplus/3.0.1 to your conanfile.


Add tomlpp to your package.json5, e.g.:

depends: [

ℹ️ What is DDS?


vcpkg install tomlplusplus

CMake FetchContent

    GIT_REPOSITORY https://github.com/marzer/tomlplusplus.git
    GIT_TAG        v3.0.1

ℹ️ What is FetchContent?

Other environments and package managers

toml++ is a fairly new project and I'm not up-to-speed with all of the available packaging and integration options in the C++ ecosystem. I'm also a cmake novice, for better or worse. If there's an integration option missing be assured that I fully support it being added, and welcome pull requests!

What about dependencies?

If you just want to consume toml++ as a regular library then you don't have any dependencies to worry about. There's a few test-related dependencies to be aware of if you're working on the library, though. See CONTRIBUTING for information.


A number of configurable options are exposed in the form of preprocessor #defines Most likely you won't need to mess with these at all, but if you do, set them before including toml++.

Option Type Description Default
TOML_API define API annotation to add to public symbols (e.g. __declspec(dllexport) on Windows). undefined
TOML_ASSERT(expr) function macro Sets the assert function used by the library. assert()
TOML_CONFIG_HEADER string literal Includes the given header file before the rest of the library. undefined
TOML_ENABLE_FORMATTERS boolean Enables the formatters. Set to 0 if you don't need them to improve compile times and binary size. 1
TOML_ENABLE_PARSER boolean Enables the parser. Set to 0 if you don't need it to improve compile times and binary size. 1
TOML_ENABLE_UNRELEASED_FEATURES boolean Enables support for unreleased TOML language features. 0
TOML_ENABLE_WINDOWS_COMPAT boolean Enables support for transparent conversion between wide and narrow strings. 1 on Windows
TOML_EXCEPTIONS boolean Sets whether the library uses exceptions. per compiler settings
TOML_HEADER_ONLY boolean Disable this to explicitly control where toml++'s implementation is compiled (e.g. as part of a library). 1
TOML_IMPLEMENTATION define Define this to enable compilation of the library's implementation when TOML_HEADER_ONLY == 0. undefined
TOML_OPTIONAL_TYPE type name Overrides the optional<T> type used by the library if you need something better than std::optional. undefined
TOML_SMALL_FLOAT_TYPE type name If your codebase has a custom 'small float' type (e.g. half-precision), this tells toml++ about it. undefined
TOML_SMALL_INT_TYPE type name If your codebase has a custom 'small integer' type (e.g. 24-bits), this tells toml++ about it. undefined

ℹ️ A number of these have ABI implications; the library uses inline namespaces to prevent you from accidentally linking incompatible combinations together.

TOML Language Support

At any given time the library aims to support whatever the most recently-released version of TOML is, with opt-in support for a number of unreleased features from the TOML master and some sane cherry-picks from the TOML issues list where the discussion strongly indicates inclusion in a near-future release.

The library advertises the most recent numbered language version it fully supports via the preprocessor defines TOML_LANG_MAJOR, TOML_LANG_MINOR and TOML_LANG_PATCH.

Unreleased language features:

  • #516: Allow newlines and trailing commas in inline tables
  • #562: Allow hex floating-point values
  • #644: Support + in key names
  • #671: Local time of day format should support 09:30 as opposed to 09:30:00
  • #687: Relax bare key restrictions to allow additional unicode characters
  • #796: Include an \xHH escape code sequence

ℹ️ #define TOML_ENABLE_UNRELEASED_FEATURES 1 to enable these features (see Configuration).

🔹TOML v1.0.0:

All features supported, including:

  • #356: Allow leading zeros in the exponent part of a float
  • #567: Control characters are not permitted in comments
  • #571: Allow raw tabs inside strings
  • #665: Make arrays heterogeneous
  • #766: Allow comments before commas in arrays

🔹TOML v0.5.0:

All features supported.


Contributions are very welcome! Either by reporting issues or submitting pull requests. If you wish to submit a pull request, please see CONTRIBUTING for all the details you need to get going.

License and Attribution

toml++ is licensed under the terms of the MIT license - see LICENSE.

UTF-8 decoding is performed using a state machine based on Bjoern Hoehrmann's 'Flexible and Economical UTF-8 Decoder'.

With thanks to:


For bug reports and feature requests please consider using the issues system here on GitHub. For anything else though you're welcome to reach out via other means. In order of likely response time: