yaml-cpp: A C++ YAML 1.2 Parser and Emitter for Build Systems That Already Use CMake

What yaml-cpp solves, and who it is aimed at

Configuration files, test fixtures and CI definitions are increasingly written in YAML, but C++ has no YAML parser in its standard library. yaml-cpp fills that gap: the README describes it as a YAML parser and emitter in C++ matching the YAML 1.2 spec. Parsing and emitting are both in scope, so the same library that reads a config file can also write one back out.

The audience is narrow on purpose. This is a library for C++ projects that already use CMake, because CMake is the only build system the README documents. It is not a command-line tool, not a service, and not a language binding. If you are writing a Python or Go program, yaml-cpp is not the answer. If you are writing a C++ program that reads a YAML config at startup, it is exactly the shape of dependency you want: one library, one link target.

The licence is MIT, which places few restrictions on how the code is used or redistributed, though you should read the LICENSE file rather than take this summary as legal advice.

How the parser and emitter are structured

The repository layout tells you most of what you need to know about the architecture. There is an include/ directory holding the public headers, a src/ directory holding the implementation, and a test/ directory. The README points readers at two wiki pages, Tutorial and How to Emit YAML, which is a signal that parsing and emitting are treated as separate concerns with separate documentation.

The API is versioned in a way that matters. The README states that 0.3.x versions provide the old API, and that 0.5.x and above all provide the new API. That means the 0.9.0 release from February 2026 uses the new API, and any tutorial you find from the 0.3 era will not compile against it. The README addresses this split only by pointing at a third wiki page for the old API.

The build produces a static library by default. You can override that with -DYAML_BUILD_SHARED_LIBS=ON. On Windows with MSVC, static builds default to the static CRT (/MT) so that yaml-cpp can link into statically linked applications such as static MFC. If you need the dynamic CRT (/MD), you set -DYAML_MSVC_SHARED_RT=ON. That is an unusual amount of platform-specific detail for a README, and it reflects a real friction point: C runtime linkage on MSVC is where most integration failures happen.

Installing yaml-cpp with CMake and parsing a first document

The README gives the build steps directly. Create a build directory, change into it, and run CMake against the parent directory. The generator flag is optional; on a UNIX-like system you omit it and get a Makefile.

mkdir build
cd build
cmake [-G generator] [-DYAML_BUILD_SHARED_LIBS=on|OFF] ..

The second step depends on the generator you chose, so the README does not give a single command. To clean up afterwards, you remove the build directory.

If you would rather not build yaml-cpp separately, the README shows how to pull it in with CMake's FetchContent. Note that GIT_TAG accepts a tag, a commit hash, or a branch name; the example uses a placeholder rather than a real tag.

include(FetchContent)

FetchContent_Declare(
  yaml-cpp
  GIT_REPOSITORY https://github.com/jbeder/yaml-cpp.git
  GIT_TAG <tag_name> # Can be a tag (yaml-cpp-x.x.x), a commit hash, or a branch name (master)
)
FetchContent_MakeAvailable(yaml-cpp)

target_link_libraries(YOUR_LIBRARY PUBLIC yaml-cpp::yaml-cpp)

Linking the yaml-cpp::yaml-cpp imported target is the part worth paying attention to. The README notes that this target sets the needed defines automatically. If you are not using CMake and you link the static library by hand, you must define YAML_CPP_STATIC_DEFINE for your target instead. Getting this wrong produces link errors that look unrelated to YAML.

For the actual parsing and emitting calls, the README does not inline an example. It directs you to the Tutorial and How to Emit YAML wiki pages. That is a real gap in the README: the build instructions are thorough, the usage instructions are one link away, and the link target is a wiki rather than versioned documentation.

Where yaml-cpp is the wrong tool

The README does not make any claim about how yaml-cpp behaves on malformed or hostile input, and it does not describe a hardened parsing mode. If you are parsing YAML that arrives from an untrusted source, that silence is the relevant fact, not a detail to skim past. YAML has constructs that can expand into large structures, and a parser's behaviour under adversarial input is a property you need to establish yourself, by reading the source or by testing, before you put it in a network-facing path.

The second limitation is the API split. If your codebase is on the old API, the README says the old API will stop receiving bugfixes in 2026. That is a deadline attached to a migration, and the migration is not described in the README beyond a pointer to the old-API wiki page. Projects that vendored yaml-cpp years ago and never touched it are the ones most exposed here.

The third is build-system lock-in. CMake is the documented path. The repository does carry BUILD.bazel and MODULE.bazel files, but the README does not document a Bazel workflow, so if you are a Bazel shop you are on your own with those files. There is also a yaml-cpp.pc.in file in the repository root, which suggests pkg-config support, but again the README does not describe it.

yaml-cpp compared with libyaml

The most direct alternative is libyaml, and the difference is the interface language, not the file format. libyaml exposes a C API, which means you manage its event-based or document-based structures manually and free them yourself. yaml-cpp exposes C++ types, which means the destructors do the cleanup and you work with nodes rather than with a stream of events.

That difference has consequences. A C API is easier to wrap from other languages and easier to keep ABI-stable across compiler versions. A C++ API is more pleasant to call from C++ and harder to bind elsewhere. If your project is C++ and you have no need to expose YAML parsing to another language, the C++ API saves you a layer of manual memory management. If you are writing a binding, or you need to link the same parser into a C library, libyaml is the more natural base.

Both are permissively licensed, and neither is a drop-in replacement for the other. The choice is about which side of the C and C++ boundary your code lives on.

Maintenance, releases and upgrade cost

The last push to the repository was on 2026-10-11, so the project is not dormant. It is not archived. The release history, however, is uneven: 0.7.0 in July 2021, 0.8.0 in August 2023, and 0.9.0 in February 2026. That is roughly one release every two to three years, with a longer gap between 0.8.0 and 0.9.0 than the earlier pair. Development activity and release cadence are not the same thing here, and anyone pinning a version should plan around the cadence rather than the commit log.

Upgrade cost depends entirely on which API you are on. Moving from 0.5.x or later to 0.9.0 keeps you on the new API, so the cost is whatever changed between those releases. Moving from 0.3.x means an API migration, and the README gives you a wiki page rather than a migration guide. The 0.3.0 release remains available if you want the old API, which is a deliberate escape hatch.

The MIT licence means you can use, modify and redistribute the library with minimal obligation, but it does not remove the need to ship the licence text with binaries you distribute. Read LICENSE for the exact terms; this is not legal advice.

Editorial conclusion

Adopt yaml-cpp if your project already builds with CMake and you want a C++ API for reading and writing YAML 1.2 without pulling in a C library and its bindings. Do not adopt it if you need a parser that has been hardened for untrusted input, or if you are still on the pre-0.5.0 API and cannot migrate, since the README states the old API will stop receiving bugfixes in 2026. Before committing, verify three things: that the tag you pin in FetchContent is the one you intend, whether you need -DYAML_BUILD_SHARED_LIBS=ON, and whether your toolchain is MSVC, where the static CRT default changes your link line.

Frequently asked questions

Official sources

1. Issues
2. jbeder/yaml-cpp on GitHub
3. License: MIT
4. README
5. Releases