Guide · Open source
How to use cpp-httplib: install, run a server and make requests
Updated · written with AI from the project's own documentation and checked against our catalogue data
cpp-httplib is a C++ library for building HTTP and HTTPS servers and clients. It is distributed as a single header file, httplib.h, which you include in your code. This guide shows how to get the library, run a small server, send a request from a client, and turn on TLS so you can serve HTTPS.
cpp-httplibyhirose/cpp-httplib · ★ 17k · MIT Install options & downloads Quick start
- 1Clone the repository. Run git clone https://github.com/yhirose/cpp-httplib to get httplib.h.
- 2Choose a compiler standard. Make sure your compiler supports C++11 or later.
- 3Include the header. Add #include with the path to httplib.h in your source file.
- 4Write a route and start the server. Create an httplib::Server, register a handler with Get, and call listen on an address and port.
- 5Make a client request. Create an httplib::Client with a base URL and call Get on a path, then check the result.
- 6Add TLS if you need HTTPS. Install OpenSSL 3.0 or later, Mbed TLS, or wolfSSL, define the matching macro, and use SSLServer or SSLClient.
Get httplib.h and add it to your project
cpp-httplib is a header-only library. There is no separate library to link; you include the header file in your code. The README's install step is to clone the repository, which gives you the httplib.h file.
The library requires a C++11 or later compiler. If you need HTTPS, you also need one TLS backend: OpenSSL 3.0 or later, Mbed TLS, or wolfSSL.
- Clone the repository to get the source files.
- Use a C++11 or later compiler.
- Install OpenSSL 3.0 or later, Mbed TLS, or wolfSSL only if you need HTTPS.
git clone https://github.com/yhirose/cpp-httplibRun a simple HTTP server
Create a server object, register a handler for a route, and start listening on an address and port. The handler receives the request and a response object. Call res.set_content to set the body and content type.
The example below listens on all interfaces on port 8080 and responds to GET /hi. The library uses blocking socket I/O, so listen() runs until the server stops.
#define CPPHTTPLIB_OPENSSL_SUPPORT
#include "path/to/httplib.h"
httplib::Server svr;
svr.Get("/hi", [](const httplib::Request &, httplib::Response &res) {
res.set_content("Hello World!", "text/plain");
});
svr.listen("0.0.0.0", 8080);Send a request with the client
The client takes a base URL in its constructor. Call Get with a path, and check the result before using it. The result holds the response on success, so read status and body from it.
- Construct httplib::Client with the scheme and host, for example http://yhirose.github.io.
- Call cli.Get("/hi") and test the result with if.
- Read res->status and res->body.
httplib::Client cli("http://yhirose.github.io");
if (auto res = cli.Get("/hi")) {
res->status;
res->body;
}Enable HTTPS with OpenSSL, Mbed TLS or wolfSSL
To use TLS, define the macro for the backend you chose before including the header. The README lists CPPHTTPLIB_OPENSSL_SUPPORT, CPPHTTPLIB_MBEDTLS_SUPPORT and CPPHTTPLIB_WOLFSSL_SUPPORT. Use only one. For the server, pass a certificate file and a key file to httplib::SSLServer.
On the client side, use httplib::SSLClient or an https:// URL with httplib::Client. You can load a CA bundle with set_ca_cert_path(). The README notes that OpenSSL requires version 3.0 or later, and that wolfSSL must be built with --enable-opensslall.
- OpenSSL: libssl and libcrypto, version 3.0 or later.
- Mbed TLS: 2.x, 3.x and 4.x are supported and auto-detected.
- wolfSSL: 5.x is supported and must be built with --enable-opensslall.
#define CPPHTTPLIB_OPENSSL_SUPPORT
#include "path/to/httplib.h"
httplib::SSLServer svr("./cert.pem", "./key.pem");
httplib::SSLClient cli("localhost", 1234);
cli.set_ca_cert_path("./ca-bundle.crt");Handle errors and certificate problems
When a request fails, the result's error() tells you the type of failure. For TLS problems, ssl_error() gives a backend-independent code and ssl_backend_error() gives the backend-specific code. Hostname verification checks subjectAltName entries only, so a certificate that names the host only in its Common Name is rejected.
Settings such as set_ca_cert_path() must be made before the first request, because the CA certificates are loaded on the first connection.
- Check the error type with res.error() when a request fails.
- Use ssl_error() and ssl_backend_error() for TLS details.
- Reissue certificates with a subjectAltName if hostname verification fails.
What people use it for
- A small C++ program that exposes a status or health endpoint over HTTP.
- A C++ tool that calls a REST API over HTTPS as a client.
- An embedded or internal service that needs HTTPS without a large framework.
- A project that wants WebSocket, Server-Sent Events or a stream API from the same library.
Frequently asked questions
Is cpp-httplib free to use?
cpp-httplib is released under the MIT licence. The source says so in the project metadata, so you can check the licence file in the repository before you ship it.
What do I need to install cpp-httplib?
You need a C++11 or later compiler. There is no separate install step beyond cloning the repository and including httplib.h. For HTTPS, you also need OpenSSL 3.0 or later, Mbed TLS, or wolfSSL.
Does cpp-httplib support HTTP/2 or HTTP/3?
No. The README says only HTTP/1.1 is supported and that HTTP/2 and HTTP/3 are not implemented. If you need those protocols, look at a different library.
Is cpp-httplib good for high-concurrency servers?
The README says the library uses blocking socket I/O and is not the right choice if you need non-blocking I/O. Pick a different library for workloads that depend on non-blocking, high-concurrency socket handling.
Can I use cpp-httplib on a 32-bit system?
The README says 32-bit platforms are not supported. The library may compile on 32-bit targets, but no security review has been done for them, and security reports that only affect 32-bit platforms are closed without action.
How does cpp-httplib compare to Boost.Beast, Pistache or Crow?
The project's comparable projects list includes Boost.Beast, cpp-netlib, Pistache and Crow. cpp-httplib's distinguishing trait from the source is that it is a single header file. Check each project's documentation for its own design and requirements.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
cpp-httplib suits C++ developers who want a simple HTTP or HTTPS server or client that they can add by including one header file, with a choice of OpenSSL, Mbed TLS or wolfSSL. It is a poor fit for apps that need non-blocking, high-concurrency I/O, HTTP/2 or HTTP/3, or any 32-bit target.
Install options & downloads