CacheLib's version number is a cache-format flag, not a release string

One constant governs cache compatibility

CacheLib has a single version number, facebook::cachelib::kCachelibVersion, and it lives in a header the README links directly.

The rule is stated without ambiguity: it must be incremented when incompatible changes are introduced, and a change is incompatible if it could cause a complication failure due to removing public API or requires dropping the cache. The compatibility notes for each increment live in CHANGELOG.md.

That definition matters more than it first appears. The version is not a library release number, it is a cache format marker. A release that does not break the API can still require every deployed cache to be discarded, and you only learn that by watching this constant rather than by reading a semantic version.

For an operator that means one thing is mandatory: record the value of kCachelibVersion alongside your own service version. If it changed between two deployments, plan the cache as cold. The alternative, discovering a mismatch from hit-rate graphs, is the expensive way to find out.

The tag naming follows a calendar convention rather than semver, with recent releases v2026.10.12.00, v2026.10.05.00 and v2026.09.28.00, which tells you releases are frequent and roughly weekly. A calendar tag is easy to sort and impossible to reason about compatibility from, which is consistent with the project pushing the compatibility story onto that one constant.

Building means running a Python script that fetches your dependencies

There is no CMake dance documented for the reader. The build goes through getdeps.py, described as the script used by many of Meta's open source tools, which downloads and builds the necessary dependencies and then invokes cmake.

Installing the system dependencies first.

git clone https://github.com/facebook/CacheLib
cd CacheLib
sudo python3 ./build/fbcode_builder/getdeps.py install-system-deps --recursive cachelib

If you want to see what would be installed before you install it, there is a dry run.

python3 ./build/fbcode_builder/getdeps.py install-system-deps --dry-run --recursive cachelib

Then the build itself.

python3 ./build/fbcode_builder/getdeps.py --allow-system-packages build cachelib

And the tests, which are built by default.

python3 ./build/fbcode_builder/getdeps.py --allow-system-packages test cachelib

The script needs Python 3.6 or newer on your path.

The dependencies it manages are named in the README: a version of boost compiled with C++14 support, and googletest, which is required to build and run the tests. On platforms other than Linux with system dependencies installed, the script mostly downloads and builds everything for you during the build step, which is convenient and slow, and in a reproducible-build environment it is the part most likely to cause friction.

Finding the output, and the four directories it lands in

Build artifacts go to a scratch directory, and you ask the script where.

python3 ./build/fbcode_builder/getdeps.py show-inst-dir cachelib

The install directory has a fixed shape, which is worth knowing because it tells you what you actually get: bin/ for executables such as cachebench, lib/ for the libraries, include/ for the headers, and test_configs/ for sample configurations.

Those sample configurations are the quiet feature. CacheLib is a library with tunable eviction heuristics and tiering behaviour, and shipping configuration examples with the build means you can start from a known configuration rather than from defaults, which for a cache with an SSD tier is the difference between a working deployment and a week of tuning.

Note the lowercase executable name cachebench against the README's CacheBench. The binary and the documentation disagree on capitalisation, which is exactly the kind of small inconsistency you hit when you go looking for the file on disk.

CacheBench is a first-class part of the project

CacheBench gets its own section in the README before anything else does, which is unusual and informative.

It is described as a standalone executable for evaluating the performance of heuristics and caching hardware platforms against production workloads. The second role is stress testing implementation and design changes to catch correctness and performance issues.

That second use is the more interesting one for an adopter. Before and after a change to your cache configuration or to a version upgrade, you can replay a workload through CacheBench and compare hit rates and latency rather than guessing from production metrics after the fact. For a library whose compatibility is expressed as a cache-format flag, having a repeatable benchmark in the box matters more than it would for most dependencies.

Full usage details and examples are on cachelib.org under the Cachebench overview, and the README does not duplicate them, so the binary is documented on the site rather than in the repository.

Four example programs, four tiers of complexity

The examples directory is the fastest way to understand what the library expects from you, and the four names form a progression.

The four are examples/simple_cache, examples/simple_compact_cache, examples/single_tier_cache and examples/proxygen_cache.

simple_cache is the minimum. simple_compact_cache adds the memory-efficiency dimension. single_tier_cache is the case where you have decided DRAM alone is enough and want the simpler path without the tiering machinery. proxygen_cache is the most involved, showing integration with a proxy server rather than a standalone service.

The presence of a compact variant and a single-tier variant tells you the design is not one-size-fits-all: CacheLib lets you trade memory overhead against functionality depending on what you are caching, and an adopter who starts with the wrong variant will discover that when their working set does not fit.

Around the code, the repository has BENCHMARKS.md at the root, which is where you would look for published numbers, BUILD.md, a .clang-format file for consistent C++ style, contrib/, and a website/ directory holding the documentation sources that produce cachelib.org.

The build badge and the security reporting path

Two operational details are worth reading before you plan a deployment.

The README says that if your target operating system's build is failing, you may check out the latest release instead, and if the release is too stale you may wish to check recent issues and pull requests for known workarounds. That is an explicit acknowledgement that main can be broken and that the tag is the safer artefact, which aligns with the versioning rule: a broken main is not a released cache format.

Security issues follow a different path. The README asks you not to open GitHub issues or pull requests for them, because that makes the problem immediately visible to everyone including malicious actors, and directs reports to Facebook's Whitehat Bug Bounty program, where the security team triages and decides bounty eligibility.

That is a reasonable process for a library from a large vendor, and it has a practical consequence: a vulnerability report from an outside user does not become a public issue, so you should watch the changelog rather than the issue tracker for security-relevant fixes.

Licensing is Apache-2.0, stated in the LICENSE file, which permits commercial use and modification with notice obligations and no copyleft.

Editorial conclusion

Adopt CacheLib if you are writing a C++ service that needs an embedded cache with an SSD tier and want a thread-safe API rather than a separate cache server, and if you are prepared to depend on the Meta dependency toolchain. Do not adopt it as a distributed cache or as a drop-in for memcached, since everything here runs inside your process. Verify first that you can build with getdeps.py in your environment, since it fetches and compiles dependencies including a C++14 boost and googletest, and record facebook::cachelib::kCachelibVersion in your own release notes, because an increment means your cache must be dropped. Apache-2.0 licensing is permissive and the project is not archived, with the last push on 2026-10-15 and weekly tags such as v2026.10.12.00.

Frequently asked questions

Official sources

1. facebook/CacheLib on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases