fbthrift: Facebook's Thrift fork with a rewritten compiler and async C++ server

What fbthrift actually is

fbthrift is not a distribution of Apache Thrift. The README states this plainly: it is an evolved internal branch that Facebook re-released to the open source community in February 2014. Originally it tracked Apache Thrift closely, but it now moves in new directions. The two most visible changes are a compiler rewritten from scratch and a fully asynchronous Thrift server. Most services at Facebook use Thrift for RPC, and some storage systems use it for serializing records on disk. If you are evaluating a Thrift implementation, you need to understand that fbthrift is a separate codebase with its own release cadence and its own design decisions, not a drop-in replacement for the Apache project.

Three pieces: code generator, serialization, RPC

The project describes itself as three things. First, a code generator that produces serializable data structures and client and server stubs for RPC in different languages. Second, a serialization framework with protocols that work across languages on those generated structures. Third, an RPC framework that frames messages and dispatches calls to application-defined functions. The stated goals are ease of use, cross-language support, performance, and backwards compatibility. The backwards compatibility point matters: fields can be added to and removed from serializable types while preserving forward and backward compatibility. That is a concrete feature, not a slogan. The compiler generates code for C++, Python, Hack, and Java, with the README calling out strong support for those languages.

The rewritten compiler and the async C++ server

The README points to the cpp2.md documentation for details on the improvements. The compiler was rewritten from scratch, and the new implementation features a fully asynchronous Thrift server. That is a significant architectural difference from the original Apache Thrift server, which typically used a thread-per-connection model. The async server is designed to handle many concurrent connections with fewer threads, which is a different performance profile. The trade-off is complexity: writing handlers for an async server requires a different mental model than blocking I/O. If your service logic is synchronous, you may need to wrap it in futures or callbacks. The documentation in cpp2.md is the place to look for specifics, but the key point is that this is not just a patched version of Apache Thrift's server.

Building with getdeps.py: commands and dependencies

The build process is centered on a script called getdeps.py. On Linux or macOS with Homebrew, you first clone the repo and install system dependencies with: ./build/fbcode_builder/getdeps.py install-system-deps --recursive fbthrift. Then you build with: ./build/fbcode_builder/getdeps.py --allow-system-packages build fbthrift. The script downloads and builds dependencies that are not available on the system. The system dependencies include Boost, CMake, OpenSSL, PThreads, Python, and Zlib. External dependencies are fmt, GFlags, GLog, and GTest/GMock. Facebook's own libraries are Fizz, Folly, Wangle, and Zstd. The Thrift compiler itself only depends on Boost, CMake, and fmt, which is worth noting if you only need the code generator. The build output lands in a scratch area, with the compiler at installed/fbthrift/bin/thrift1 and the C++ library at installed/fbthrift/lib/libthriftcpp2.a. There is a run_cmake.py script in the scratch build directory for iterating on CMake configuration. CMake options include THRIFT_COMPILER_ONLY to build just the compiler, and enable_tests to turn on tests.

Integrating generated code with CMake

For projects that use CMake, the README describes a ThriftLibrary.cmake file that you include. It provides a macro called thrift_library with arguments for file_name, services, language, options, file_path, and output_path. The macro generates a library named file_name-<language>. For a Test.thrift compiled as cpp2, you get a library called Test-cpp2. This library should be added as a dependency to any source or header file that includes generated code. That is a concrete integration path, but it assumes you are using CMake and are willing to adopt Facebook's build conventions. If your build system is something else, you will need to invoke thrift1 directly and manage the generated files yourself. The README does not give an example of a direct compiler invocation, so you would need to read the compiler's help or existing build files to figure out the exact flags.

Python support: a separate wheel build

The Python bindings, called thrift-python, are built separately as a wheel. The README recommends a container build with Docker BuildKit. The commands are: docker buildx build -t fbthrift-python-build -f .devcontainer/Containerfile ., then docker run -it -v $(pwd):/fbthrift -w /fbthrift fbthrift-python-build bash. Inside the container you install system deps, build, test, and install the wheel with pip. The exact commands are: python3 build/fbcode_builder/getdeps.py install-system-deps --recursive fbthrift-python, then build, then test, then pip3 install $(python3 build/fbcode_builder/getdeps.py show-inst-dir fbthrift-python)/share/thrift/wheels/thrift-*.whl. The README notes the wheel is portable and can be installed into any compatible Python environment. This is a separate path from the C++ build, which means you have two build systems to maintain if you need both languages.

Limitations and when it is the wrong tool

The most obvious limitation is the release history. The last release listed is v2020.08.24.00 from August 2020, and the last push to the main branch is the same date. That means the public repository has not seen activity in years, even though the project may be used internally at Facebook. If you are looking for an actively maintained open source project, this is a red flag. You would be relying on a snapshot of code that may not receive fixes or security updates. Another limitation is the dependency chain. Folly, Wangle, and Fizz are large libraries with their own release cycles. If your organization does not already use them, you are pulling in a significant amount of code just to get an RPC framework. The build process with getdeps.py can download and build these for you, but that adds time and complexity. For a small service that just needs simple RPC, a lighter framework like gRPC or even plain HTTP might be easier to adopt. fbthrift is also not a drop-in replacement for Apache Thrift, so if you have existing .thrift files and clients written against the Apache compiler, you will need to verify that fbthrift's compiler accepts them and generates compatible code.

The alternative: Apache Thrift itself

The direct alternative is Apache Thrift, which the README explicitly says fbthrift is not a distribution of. Apache Thrift is a separate project with its own compiler, its own runtime libraries, and a broader language support matrix. The key difference in approach is that Apache Thrift aims to be a stable, community-governed standard, while fbthrift is an internal branch optimized for Facebook's scale and use cases. Apache Thrift's server is not fully asynchronous by default, and its compiler has a different code generation strategy. If you need a Thrift-compatible protocol but want a more conservative, widely adopted implementation, Apache Thrift is the safer choice. However, if you need the performance characteristics of an async C++ server and you are already comfortable with Facebook's libraries, fbthrift offers something that Apache Thrift does not. The choice comes down to whether you value innovation over stability, and whether you can tolerate the maintenance burden of a project that may not have regular public releases.

Editorial conclusion

fbthrift suits teams already invested in Facebook's ecosystem, especially those needing a high-performance async C++ server and cross-language RPC with Python, Hack, or Java clients. It is not the right choice for projects that want a stable, community-governed Thrift implementation, since fbthrift is an internal branch that evolves independently and has not had a release since August 2020. Before adopting, verify that the specific language bindings and compiler features you need are present in the current main branch, and confirm that the dependency chain (Folly, Wangle, Fizz) fits your build environment, as getdeps.py will otherwise download and build them for you.

Official sources

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