facebook/fbthrift: a Thrift branch with a rewritten compiler and an async C++ server

What facebook/fbthrift is, and who actually needs it

Thrift is three things at once: an IDL compiler, a serialization format, and an RPC framing layer. Facebook's branch keeps that shape but changes the internals. The README is explicit that this is not a distribution of Apache Thrift: it is an evolved internal branch re-released in February 2014, and it now evolves in new directions, with the compiler rewritten from scratch and a fully asynchronous Thrift server added.

The audience is narrow and specific. If you are writing a C++ service and want a generated server that is asynchronous by construction, this branch is the one that ships that model; the README points at the ThriftServer documentation for cpp2. If you are writing Python and want the thrift-python wheel, the repository has a dedicated build path for it. If you are on Hack or Java, the README claims strong support, but the visible build documentation is C++ and Python.

What it is not for: teams that want a maintained, versioned, vendor-neutral Thrift. The last push to this repository was on 2020-08-28, and the most recent release listed is v2020.08.24.00 from the same date. The previous release, 0.19.0, dates to 2015-01-21. That gap is the whole story of the project's release cadence.

The compiler rewrite and the async server are the two real differences

The README states the compiler was rewritten from scratch. That matters because the compiler is what turns .thrift files into client and server stubs, and a rewrite is not a refactor: the generated code shape can differ from Apache Thrift's output even when the IDL is identical. It also means the compiler binary is named thrift1, not thrift, which is a small but real friction point when scripts assume the Apache name.

The second difference is the server. The README describes the new implementation as featuring a fully asynchronous Thrift server and links to the cpp2 documentation. This is the reason to choose this branch over upstream if you are on C++: the server model is the product. The serialization protocols and the RPC framing are still Thrift in the ordinary sense, so a Python client talking to a C++ server remains the canonical example, and the README uses exactly that pairing.

The build graph is where the cost shows up. The compiler itself only depends on Boost, CMake and {fmt}, which is a light set. The full build pulls in Folly, Fizz, Wangle and Zstd from Facebook, plus GFlags, GLog, GTest and GMock. Fizz is the TLS layer and Wangle is the service framework; both are part of the same family and both are needed for the server side. That is a large dependency surface for a serialization library, and it is the direct consequence of shipping an async server rather than just a codec.

Building fbthrift with getdeps.py

The documented entry point is the getdeps.py script under build/fbcode_builder. On Linux or macOS with Homebrew, the README's first step installs system dependencies so the build does not have to compile them. Run these from the repository root after cloning:

git clone https://github.com/facebook/fbthrift
cd fbthrift
./build/fbcode_builder/getdeps.py install-system-deps --recursive fbthrift

On other platforms, or on Linux without system dependencies, the README says getdeps.py will mostly download and build them during the build step. The build command is the same script with the build subcommand:

./build/fbcode_builder/getdeps.py --allow-system-packages build fbthrift

getdeps.py invokes cmake and writes into a scratch area whose location appears in the logs. The README names two artifacts to look for there: installed/fbthrift/bin/thrift1, the compiler, and installed/fbthrift/lib/libthriftcpp2.a, the client and server library. If you need to re-run cmake while iterating, the README says a run_cmake.py is emitted into the scratch build/fbthrift directory. Two CMake options are documented: THRIFT_COMPILER_ONLY, off by default, which builds only the compiler, and enable_tests.

For Python, the README recommends a container build with Docker BuildKit:

docker buildx build -t fbthrift-python-build -f .devcontainer/Containerfile .
docker run -it -v $(pwd):/fbthrift -w /fbthrift fbthrift-python-build bash

Inside that container the documented sequence installs dependencies, builds, tests, and then installs the wheel from the path that show-inst-dir prints:

apt-get update
python3 build/fbcode_builder/getdeps.py install-system-deps --recursive fbthrift-python
python3 build/fbcode_builder/getdeps.py build fbthrift-python
python3 build/fbcode_builder/getdeps.py test fbthrift-python
pip3 install $(python3 build/fbcode_builder/getdeps.py show-inst-dir fbthrift-python)/share/thrift/wheels/thrift-*.whl
python3 -c "from thrift.python.types import StructMeta; print('thrift-python installed successfully')"

The README notes the wheel is portable and can be installed into any compatible Python environment. That final one-liner is the check that tells you the install worked: it imports StructMeta from thrift.python.types and prints a confirmation string.

Wiring generated code into a CMake project

The repository ships ThriftLibrary.cmake at the top level. Including it gives you a thrift_library macro whose arguments are documented in the README as file_name, services, language, options, file_path and output_path. The naming rule is worth remembering because it drives your target_link_libraries lines: compiling Test.thrift as cpp2 produces a library called Test-cpp2. The README says that library should be added as a dependency to any source or header file that includes generated code.

That is the whole integration story as far as the README goes. It does not document a CMake config package for find_package, a pkg-config file, or an installed export set, so a project that expects to consume fbthrift as a prebuilt dependency rather than building it in-tree will have to work that out from the CMakeLists files. This is a genuine gap for anyone outside the getdeps workflow, and it is the kind of thing that turns a two-hour evaluation into a two-day one.

Where fbthrift is the wrong tool

The repository has not been pushed to since 2020-08-28. That is not a judgement about code quality; it is a statement about what you get. If your threat model includes keeping up with compiler and TLS library changes, or if you need a release cadence you can plan around, this branch gives you neither. The changelog between 0.19.0 in 2015 and v2020.08.24.00 in 2020 is not described in the README, and the tags do not follow a semantic versioning scheme, so pinning to a version means pinning to a date.

The dependency graph is the second problem. Folly, Fizz, Wangle and Zstd all come from the same organization, and building them from source through getdeps.py is the documented path. If your environment cannot build that stack, or if you need a Thrift implementation that vendors cleanly into a distro package, the compiler-only build is the escape hatch: THRIFT_COMPILER_ONLY depends only on Boost, CMake and {fmt}. But that gives you code generation without the async server, which is most of the reason to be here.

Finally, cross-language claims are broader than the visible documentation. The README says Thrift enables these features in all major languages and names C++, Python, Hack and Java as the strong ones, but the build instructions cover C++ and Python. If you are evaluating this for Java or Hack, the README will not tell you how to build or install it.

fbthrift versus Apache Thrift: the difference is the server, not the IDL

Apache Thrift is the upstream project, and the README is careful to say this branch is not a distribution of it. The practical difference is not the wire format or the IDL syntax, which are shared heritage. It is that Apache Thrift is a multi-vendor project with its own release process, while fbthrift is a single-organization branch that diverged and rewrote its compiler. If you want a Thrift implementation with an external governance story and a release history you can point at, upstream is the answer. If you want the async C++ server described in the cpp2 documentation, upstream is not the answer, because that server lives here.

A second comparison is worth naming because it shows up in the related searches: Thrift versus gRPC. The README does not make this comparison, so the honest version is structural. Thrift, in both branches, is built around a schema file compiled ahead of time into stubs, with pluggable serialization protocols and a framing layer. That is the design the README describes as a code generator, a serialization framework and an RPC framework. Whether that is better than any other RPC system depends on your language mix and your tolerance for a compiler in the build, and this repository does not argue the case.

Editorial conclusion

Adopt facebook/fbthrift only if you need the generated C++2 server model or the thrift-python wheel and can accept a branch whose last push was 2020-08-28. Do not adopt it as a drop-in Apache Thrift replacement: the README says the compiler was rewritten and the two are evolving separately, so wire compatibility between generated code and the Apache toolchain is not something the README promises. Before committing, clone the repository, run getdeps.py install-system-deps and build fbthrift, and confirm that installed/fbthrift/bin/thrift1 and installed/fbthrift/lib/libthriftcpp2.a appear in the scratch path on your platform.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes