farmhash: a fast hash family for hash tables, not for cryptography

What it is, and what it is not for

farmhash is a family of hash functions for strings and other data, and the readme states the limitation in the first paragraph: the functions mix the input bits thoroughly but are not suitable for cryptography.

That sentence is the single most important thing to know before choosing the library, and it is the reason the project exists separately from the cryptographic hash functions. A fast hash for a hash table has different requirements from a hash that has to be unguessable, and a library that confuses the two is dangerous. farmhash is explicit that it is on the first side of that line.

The reference implementation is in C++ under a friendly MIT licence, and the readme credits the lineage: every member of the family was designed with heavy reliance on previous work by Jyrki Alakuijala, Austin Appleby, Bob Jenkins, and others. That is the standard lineage of the fast non-cryptographic hashes, and naming it is a courtesy rather than a detail.

There is also a document in the repository, Understanding_Hash_Functions, which the readme recommends reading before using the library. A file whose name is that plain usually means what it says, and it is the background reading for the rest of the readme.

The project is MIT licensed, was automatically exported from the old code hosting site, and the last push was on 2026-06-05. There are no tagged releases in the repository, so the version you use is the commit you pin, and the readme carries a version number of its own.

The recommended pattern, and why it is a wrapper function

The usage section makes an argument that is unusual to see stated so plainly, and it is the most useful part of the documentation.

The belief is that the typical hash function is mostly used for in-memory hash tables and similar. That use case allows hash functions that differ on different platforms, and that change from time to time. And for that case, the recommendation is to use wrapper functions in a header file with a comment saying that it may change from time to time, may differ on different platforms, and may change depending on the debug macro being defined.

Some projects need a forever fixed, portable hash function, and the readme says to use wrapper functions again, but with a very different comment on them. So the API shape is the same in both cases and the difference is entirely in what you write above it.

That is a good design, and it is the opposite of what most libraries do. A library that exports the hash directly is telling you the value is stable. A library that exports a wrapper is telling you the value is whatever the platform decides, and the wrapper is where you put your own stability policy if you need one.

The sample of those wrappers is in the header file in the source directory, and the readme's hope is that most people need nothing more than that header and the corresponding implementation file. Those two files are a usable and relatively portable library on their own, with the configure script being optional for the people who want to run make install afterwards.

There is one portability snag named in the same paragraph, and it is the kind of detail that saves a build on an unusual toolchain: if the compiler does not provide the branch prediction builtin, you may need to define the macro that turns that dependency off.

Compile time selection, and the flags that drive it

The wrapper functions, such as the general Hash call, can select among several hash functions, and the selection happens at compile time rather than at run time.

Two things drive it. The first is the machine architecture, with the size of the pointer type given as the example, and the second is the availability of vector instructions, with SSE4.1 named. The implementation uses conditional compilation, and possibly the compiler's multiversioning, to pick the variant.

Getting the best out of it therefore means thinking about compiler flags. The named ones are the AES, SSE4.2, and AVX flags, and the readme explains that these are the flags that make the compiler emit more types of machine instructions than it otherwise would.

There are two ways to use them. If you are confident that you will only run on systems with SSE4.2 and the AES instruction set, you can communicate that to the compiler, as explained in the implementation file, and the build will take the fast path. If you are not sure, you pass the flags where you can and let the conditional compilation in the implementation file make the appropriate choices.

The optimisation level matters too. Trying the third optimisation level or other flags is suggested, and the author reports having found that feedback directed optimisation improved the speed, which is a technique that profiles the binary and recompiles it with the hot paths optimised, and it is the kind of thing that works well for a hash function because the hot paths are narrow and predictable.

So the performance story of farmhash is not that the algorithm is clever in the abstract, it is that the library ships several implementations of similar algorithms and picks the one your processor can run fastest.

The configure script, and the cross-platform testing problem

The build system is based on autoconf, and it is presented as an option rather than as the main path.

The configure script creates a configuration header, and the compiler flags default to debugging information with the second optimisation level, which the readme says may or may not be best. The recommended first attempt, if you are going to use the script at all and do not already know that your system lacks the AVX and AES instruction sets, is this.

  ./configure CXXFLAGS="-g -mavx -maes -O3"
  make all check

If that fails, the readme tells you how to recover: retry with the AVX and AES flags removed, or with AVX replaced by one of the earlier instruction set levels. The recovery path is the useful part, because it tells you which flag is the likely culprit in which direction.

There is one configure option of its own, to make the branch prediction builtin optional. Without it, the assumption is that the library is compiled with compilers that provide it. In practice, some of the variants may be slightly faster with it, and the readme is clear that it is not important and affects speed only.

The cross-platform testing problem is the part of this documentation that deserves more attention than it usually gets, and the explanation is admirably honest. The check target creates an object file with the chosen compiler and tests it, and that object file will not necessarily contain all of the code that would be used when the same source is compiled for other platforms. The downside is stated plainly: the paths that were not tested may not actually work when you try them.

The project says the developers try hard to prevent such problems and asks to be told about bugs. And there is a way to help yourself, which is to compile your program with the self test flag set, which makes the library run its own test at program start, write the result to standard output, and exit. The check target does exactly that, and the source of the test is in the test file in the source directory.

Pinning a variant, and the big-endian caveat

There is a way to remove the compile time selection from the equation, and it matters for anyone who needs a value that does not move.

The trick is to choose a FarmHash variant by name, with names in the form of a namespace and a function, such as the 32-bit and 64-bit hash calls in the two named variants. Those compute the same hash function regardless of conditional compilation, multiversioning, or endianness.

The qualification is in the readme and it should not be skipped: consult the comments and the conditional definitions for the requirements, and note that they are not all guaranteed to work on all platforms. The named variants are the escape hatch from the automatic selection, and using one transfers the responsibility for whether it works on your target from the library to you.

The first of the known issues is about endianness. FarmHash was developed with little-endian architectures in mind, and it should work on big-endian, but less work has gone into optimising for those platforms. To make it work properly there you may need to modify the wrapper header or the compiler flags so that the big-endian macro is defined, although there is logic in the library that tries to work it out automatically.

That is a reasonable default, and it is also a reminder that a library which is fast everywhere and correct everywhere is a harder thing to write than a library that is fast on the platform it was written for.

The other two known issues are about the shape of the project rather than its behaviour. The implementation is fairly complex, which is a warning to anyone about to modify it. And the techniques described in the instructions file in the development directory, which let the hash developers regenerate the source files from the sources in that directory, are described as hacky and not very portable.

Hash quality, and what SMHasher is for

The last section of the readme is about testing, and it is short enough to quote the important parts of.

The hash functions are tested with SMHasher, among other things. The readme is careful about the tool: SMHasher is not perfect, but it seems to find almost any significant flaw.

The mechanics of the test are worth knowing, because they explain why the seed handling looks the way it does. SMHasher is designed to pass a 32-bit seed to the hash functions it tests. For the functions in this library that accept a seed, the given seed is used directly, padded with zeroes as needed. For the functions that do not accept a seed, the concatenation of the seed and the input string is hashed instead.

And then the reassurance, which is also the most useful sentence in the section: some minor flaws in the 32-bit and 64-bit functions are harmless, as the primary use of these functions will be in hash tables.

That is the honest framing of the whole quality discussion. A hash function that is not perfect is a problem for a cryptographic hash, where a collision is a break. For a hash table, where the requirement is that equal keys produce equal hashes and different keys almost never collide, a rare minor flaw is a performance curiosity rather than a defect.

The repository layout is what an autoconf project looks like. There is the configure script with its helpers, the makefiles in both template and generated form, the m4 directory of macros, the source directory, the development directory with the sources the implementation is generated from, and the documentation file about hash functions. There is also a news file, a licence file, and the usual set of install helpers that every autoconf project carries whether it needs them or not.

Editorial conclusion

farmhash fits a C++ project that needs a fast hash for an in-memory hash table, on strings or on other data, and that is prepared to accept that the value may differ between platforms and between builds. It does not fit anything that needs a cryptographic hash, because the readme says the functions are not suitable for cryptography, and it does not fit a project that needs one fixed hash forever without doing extra work to pin the variant. Verify first that you are using it for a hash table rather than for a signature, that your build enables the vector instructions you intend to require, and that if you need a fixed value across platforms you pin the variant explicitly instead of relying on the compile time selection.

Frequently asked questions

Official sources

1. google/farmhash on GitHub
2. Issues
3. License: MIT
4. README