Pistache: a C++17 REST toolkit for services that already live in C++

What Pistache solves for a C++ service

Most HTTP frameworks assume you are willing to run a second runtime next to your compiled code. Pistache takes the opposite position: it is entirely written in pure C++17 and provides an HTTP and REST toolkit with a C++ API, so a service that already parses binary payloads, talks to native libraries or holds tight latency budgets does not need a bridge layer. The audience is narrow and specific. It is for engineers writing C++ servers who want routing, request and response objects, and an HTTP client in the same language and the same build. It is not a general web framework and it does not try to be one. The README is explicit that Pistache supports Linux, macOS, Windows and BSD, with separate build notes for macOS, Windows and BSD, and the Debian and Ubuntu packages are built for amd64, arm64, armhf, i386, ppc64el, riscv64 and s390x. That architecture list is the clearest statement of intent in the repository: this is infrastructure meant to run on servers and embedded boards, not a teaching project.

The mechanism: a library, not a process

Pistache ships as a shared and static library rather than a standalone server binary. When installed, according to the README, it produces libpistache.so.X.Y.Z, the soname soft link libpistache.so.X.Y, the linker name libpistache.so, and the static archive libpistache.a. Your program links against it and owns the process, which means you control threads, signals and shutdown rather than delegating them to a runtime you cannot inspect. The examples/ directory shows the intended shape of an application: hello_server.cc and http_server.cc for basic serving, rest_server.cc and rest_description.cc for route declaration, custom_header.cc for header handling, http_client.cc for outbound requests, and http_server_shutdown.cc for stopping the server from inside the program. That file list is effectively the table of contents for the API, which matters because the README states the project is still looking for a volunteer to document the API fully and that only partial documentation is available at pistacheio.github.io/pistache/. The design trade-off is visible here. You get a library that composes with existing C++ code and no runtime dependency, and in exchange you read headers and examples instead of a reference manual.

Installing Pistache from a precompiled package

The README recommends precompiled packages if you have no need to modify the source, and says this will save you time. On Debian and Ubuntu the library has been in the official repositories since Debian 12 and Ubuntu 23.10 under the package name libpistache-dev. If your distribution is older, the project maintains PPAs. The stable PPA is described as receiving release packages from time to time:

sudo add-apt-repository ppa:pistache+team/stable
sudo apt update
sudo apt install libpistache-dev

After that, the header include path and the linker name are available to your build. For a newer snapshot, the README documents a separate unstable PPA that builds daily, using the same two commands with ppa:pistache+team/unstable in the first line. On macOS the README points to Building on macOS.txt and says Pistache can be installed with Homebrew. There are also files named Building on Windows.txt and Building on BSD - FreeBSD, OpenBSD and NetBSD.txt at the top level, so those platforms are supported but not covered by the package route.

For a first real use, the repository's examples/ directory is the starting point rather than a tutorial. examples/hello_server.cc is the minimal program, and examples/meson.build shows how the examples are wired into the Meson build. Building from source requires the dependency list in the README: Meson, Doxygen, Googletest, OpenSSL, RapidJSON, Hinnant Date, brotli, zstd and libevent. That is a heavier build environment than the package install, which is the argument for using libpistache-dev unless you are changing the library itself.

What the thin documentation costs you

The README does not pretend otherwise: it asks for a volunteer to document the API fully. Partial documentation exists at the project site, and the README links to third-party material, including an article on building an API with Pistache, a video, and a German piece on slim microservices. There is also a benchmark comparison against other C++ REST APIs hosted in a separate repository by a contributor, not by the maintainers. Treat all of that as orientation, not as a specification. The practical consequence is that questions about error handling, connection limits, timeouts and shutdown semantics are answered by reading include/ and src/ or by asking in #pistache on Libera.Chat, which the README names as the maintainers' channel. For a team evaluating the library, that is the main cost to price in: adoption time is measured in reading source, not in reading docs. If your project needs a documented contract before you can get sign-off, this is the wrong tool today, regardless of how well the code performs.

Versioning and the ABI before 1.0

The README is unusually direct about a risk that many C++ libraries leave implicit. The library's interface version is not the same as the release version, and the plan to make the major release version match the soname version applies only after the 1.0 release. Until then, the soname version follows feature releases. The README warns that if a contribution modifies the interface and the interface versions are not updated, user applications and build environments will eventually break, either by linking against an incorrect version or, worse, by linking correctly and behaving undefined at runtime. The file to watch is version.txt, which carries the interface version and a commit date that contributors are told to update. The practical reading for an adopter is that upgrading Pistache across a feature release can require a rebuild and possibly a recompile of everything linked against it, because the soname moved. That is a normal cost for pre-1.0 C++ libraries, and the project documents it rather than hiding it. It also means a pinned package version plus a rebuild step is safer than floating on whatever the distribution ships.

Pistache versus a header-only C++ HTTP library

The closest alternative in the C++ space is a header-only HTTP library that you drop into your source tree and compile with your own target, with no shared object and no package manager involved. The difference is not performance, it is distribution. A header-only library removes the soname problem entirely: there is no libpistache.so.X.Y to match, no interface version to track in version.txt, and no risk that a distribution upgrade swaps the library underneath your binary. Pistache takes the opposite route deliberately. The README explains that Meson does not support the equivalent of libtool's export-symbol and export-regex, so the project sets the SONAME directly and ships a versioned shared object plus a static archive. That buys you a smaller binary, a single library shared across processes, and precompiled packages on Debian, Ubuntu and Homebrew, at the cost of the ABI discipline described above. If your deployment is a container where you rebuild everything anyway, the shared library advantage is small and a header-only dependency is simpler. If you ship binaries that link against a system library, Pistache's packaging is the reason to prefer it.

Licence and contribution model

Pistache is released under the Apache License 2.0, and the repository carries LICENSE and LICENSES/ entries plus REUSE compliance metadata and an SPDX header in the README itself. For adopters, Apache-2.0 is a permissive licence with an explicit patent grant, which is generally the reason projects pick it over MIT for infrastructure code. This article is not legal advice; if your organisation has a licence review process, the file to hand over is LICENSE, and the REUSE badge in the README indicates the project tracks per-file licensing. On maintenance, the repository is not archived and the last push was on 2026-07-11, which is recent enough that the project cannot be described as dormant. The most recent releases listed are v0.4.26, v0.4.25 and v0.4.23, all from December 2024, and all described as builds for Linux, macOS, BSD and Windows. The gap between the release tags and the last push is worth noting: release cadence and commit activity are not the same thing, and the versioning section above explains why a tag matters more than a commit when you are linking against a shared object. Pistache was originally created by Mathieu Stefani and, per the README, he continues to contribute to maintenance and development supported by a team of volunteers, with the Launchpad Team administering the Ubuntu packages.

Editorial conclusion

Adopt Pistache when your request handling is already C++ and you want the HTTP layer to stay in the same language and build system. Do not adopt it if you need a fully documented API surface, a stable ABI before 1.0, or a framework with a large third-party ecosystem: the README states the project is still looking for a volunteer to document the API fully. Before committing, read the examples/ directory against your own routing needs, confirm your distribution ships a new enough libpistache-dev, and check version.txt because the README says the soname follows feature releases until 1.0, so a minor upgrade can change the library interface.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. pistacheio/pistache on GitHub
3. Project website
4. README
5. Releases