C++ Requests (cpr) — Curl for People

Introduction

cpr brings the simplicity of Python's Requests library to C++. Instead of wrestling with libcurl's C API, developers write clean, expressive HTTP calls using familiar patterns like cpr::Get, cpr::Post, and named parameters.

What cpr Does

• Performs HTTP GET, POST, PUT, DELETE, PATCH, and HEAD requests with a fluent API
• Handles authentication, cookies, redirects, and SSL verification automatically
• Supports asynchronous requests via std::future for non-blocking I/O
• Manages multipart file uploads and form-encoded data
• Provides session objects for connection reuse and persistent settings

Architecture Overview

cpr is a C++ wrapper around libcurl. Each request function constructs a curl handle, applies named parameters (URL, headers, body, auth), executes the transfer, and returns a Response object with status, headers, and body. Sessions maintain a curl handle across requests for connection pooling.

Self-Hosting & Configuration

• Install via vcpkg, Conan, or CMake FetchContent with automatic libcurl bundling
• Link with cpr::cpr in CMake; libcurl is fetched and built automatically if not found
• Set timeouts with cpr::Timeout{milliseconds} parameter
• Configure SSL certificates with cpr::SslOptions
• Use cpr::Session for persistent headers, cookies, and base URLs

Key Features

• Python-Requests-style API that feels natural to C++ developers
• Automatic libcurl bundling eliminates manual dependency management
• Async request support via cpr::GetAsync returning std::future
• Built-in support for HTTP/2 and connection multiplexing via libcurl
• Thread-safe session objects for concurrent request patterns

Comparison with Similar Tools

• libcurl (C) — libcurl is the underlying engine; cpr adds a modern C++ API layer that reduces boilerplate significantly
• cpp-httplib — cpp-httplib is header-only with its own HTTP stack; cpr leverages libcurl's mature networking layer
• Boost.Beast — Beast provides low-level HTTP on Boost.Asio; cpr is higher-level and simpler for typical REST calls
• httplib — httplib suits simple use cases; cpr handles advanced scenarios like HTTP/2, proxies, and async natively

FAQ

Q: Does cpr bundle libcurl? A: Yes. If libcurl is not found on the system, CMake fetches and builds it automatically.

Q: Is cpr thread-safe? A: Individual requests are thread-safe. Session objects should not be shared across threads without synchronization.

Q: Does cpr support HTTP/2? A: Yes, when the underlying libcurl is built with HTTP/2 support (nghttp2).

Q: What C++ standard does cpr require? A: cpr requires C++17 or later.

Sources

• https://github.com/libcpr/cpr
• https://docs.libcpr.org/