facebook/proxygen: a C++ HTTP library for servers, proxies and HTTP/3

What facebook/proxygen is for, and who should reach for it

Proxygen is the core set of C++ HTTP abstractions used inside Facebook, released as a library. The README is explicit that the release focuses on the common HTTP abstractions and a simple HTTPServer framework, and that internally the code is the basis for many HTTP servers, proxies and clients. The protocols covered are HTTP/1.1, SPDY/3, SPDY/3.1, HTTP/2 and HTTP/3.

That framing decides the audience. If you are writing a C++ service that terminates HTTP or speaks it upstream, and you want the protocol work handled rather than reimplemented, this is the target case. If you want an nginx replacement you can install and configure with a text file, you are in the wrong place: proxygen is a library you link against, and the README says so directly. The interesting part is that the same handler and transaction interfaces are used both to create requests and to handle responses, which is why the same code base can back a server, a forward proxy and a curl-like client.

Session, codec, transaction, handler: the four abstractions that explain everything

The README names four central abstractions in proxygen/lib: session, codec, transaction and handler, and adds that it does not generally recommend building on them directly. The data flow is worth reading twice, because it explains the API shape.

Bytes arrive from the wire. The HTTPCodec held inside HTTPSession parses them into higher-level objects and attaches a transaction identifier. HTTPSession keeps the mapping from that identifier to HTTPTransaction objects, one per request/response pair. HTTPTransaction then forwards the call to a handler implementing HTTPTransaction::Handler, which holds the business logic. Egress runs the same path in reverse: the handler calls back into the transaction, the transaction reaches the session, and the codec turns the higher-level call into bytes on the wire. HTTPSession is specialised depending on whether the connection issues requests or answers them.

Above that sits proxygen/httpserver, described as the recommended way to interface with proxygen when acting as a server and you do not need the full control of the lower layers. There the components are HTTPServer, RequestHandlerFactory and RequestHandler: the server takes configuration and a factory, the factory spawns a RequestHandler per request, and subclasses send their response through the inherited protected member downstream_. If you only remember one thing about this library's design, it is that the low-level path is generic across client and server roles while the httpserver path is deliberately narrower.

Building proxygen and running the echo server

The README states the project has been tested on Ubuntu 18.04 and macOS, and that compiling proxygen and its dependencies needs at least 3 GiB of memory. That memory figure is a real constraint on small CI runners and containers.

The easy path is the two scripts in the proxygen directory. build.sh fetches and builds all dependencies plus proxygen, install.sh installs the result, and the temporary _build directory can be removed and the pair re-run to rebase dependencies and rebuild.

./build.sh
cd _build/ && make test
cd .. && ./install.sh

If you prefer a package manager, the README documents vcpkg, noting that the port is kept up to date by Microsoft team members and community contributors and that an out-of-date version should be raised on the vcpkg repository rather than here.

git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh
./vcpkg integrate install
./vcpkg install proxygen

For a first real use, the README points at the echo sample under proxygen/httpserver/samples/echo/. After building, the binary is at _build/proxygen/httpserver/proxygen_echo, and the README shows curl against it on port 11000 returning 200 OK with a Request-Number header and an empty body.

_build/proxygen/httpserver/proxygen_echo
curl -v http://localhost:11000/

Other samples listed are proxygen_push for HTTP/2 server push, proxygen_static for static files, proxygen_proxy for a simple fwdproxy, and proxygen_curl as a curl-like client.

Where proxygen gets in your way

The first limitation is the one the README states outright: this is a library, not a server product. There is no configuration file, no service unit, no admin endpoint. Everything above the protocol layer is code you write, and the samples are demonstrations rather than deployable services.

The second is build cost. Proxygen and folly are Autotools-based, and the README says that on other platforms you may need to install several packages first. Only Ubuntu 18.04 and macOS are named as tested. A 3 GiB floor for compiling proxygen and its dependencies is not a rounding error; it rules out the smallest build machines and makes caching dependencies worth planning for.

The third is the abstraction boundary. The README says the four core abstractions are the lowest level and that building directly on them is not generally recommended, which means the recommended surface for a server is httpserver and its RequestHandler interface. If your design needs behaviour that httpserver does not expose, you are choosing between the lower-level interfaces the project itself steers you away from and a fork. HTTP/3 support is real but conditional: the README says it depends on Facebook's mvfst library for IETF QUIC, so that dependency has to build too.

Finally, the repository metadata reports the licence as NOASSERTION rather than a recognised identifier. The LICENSE file is at the top level and is the thing to read; the metadata alone will not tell you the terms.

proxygen compared with nginx and with writing your own HTTP layer

The comparison people search for is proxygen versus nginx, and the difference is categorical rather than feature-by-feature. nginx is a server process you install, configure and reload; proxygen is a C++ library you compile into your binary. With nginx you put application logic behind a reverse proxy and communicate over a socket. With proxygen the request handling code runs in the same process as the protocol stack, and you implement RequestHandler subclasses instead of writing a backend.

That gives proxygen tighter control over the connection lifecycle and lets you use the same transaction and handler interfaces for outbound requests, which is how the README describes the curl-like client sample sharing the server's abstractions. It costs you the operational tooling that comes with a standalone server, and it makes the build your problem. Choosing nginx and a separate application process is usually the cheaper decision unless the HTTP layer itself is what you are building.

The other alternative is writing your own HTTP parsing and connection management. Proxygen's answer to that is the codec, session and transaction split, plus HTTP/1.1 through HTTP/3 in one stack and HTTP/3 through mvfst. Reimplementing that range is a multi-year project, which is the honest argument for taking the dependency.

Maintenance, releases and what upgrading costs you

The repository is not archived, and the last push was on 2026-09-21. Releases follow a weekly cadence in the repository history: v2026.09.07.00, v2026.09.14.00 and v2026.09.21.00, each tagged and dated. That is a fast-moving project, and the version scheme is date-based rather than semantic, so a version number tells you when it was cut, not what changed.

For an adopter, that cadence is the upgrade cost. There is no long-term support branch described in the README, and the build instructions assume you are building the current tree with its dependencies rather than pinning to a stable line. If you vendor proxygen, you are also vendoring folly and, for HTTP/3, mvfst, and the README's note that build.sh && install.sh can be re-run to rebase dependencies is effectively the documented upgrade procedure.

On licensing, the repository metadata reports NOASSERTION, which is not a licence name. The top-level LICENSE file is the authoritative document, and if the terms matter to your organisation, that file is what to read. Nothing here should be treated as legal advice.

Editorial conclusion

Adopt facebook/proxygen when you are writing a C++ service that needs the same transaction and handler interfaces for both issuing requests and answering them, or when HTTP/3 over mvfst matters to you. Do not adopt it if you want a binary you can configure and run, or if you cannot give a build at least 3 GiB of memory. Verify first that your toolchain matches the tested platforms (Ubuntu 18.04 and macOS per the README), that you can build folly and its dependencies through build.sh or get vcpkg to supply the port, and which licence the LICENSE file actually carries, since the repository metadata reports NOASSERTION rather than a named licence.

Frequently asked questions

Official sources

1. facebook/proxygen on GitHub
2. Issues
3. README
4. Releases