HH-suite3: sensitive protein homology search built on profile-to-profile HMM alignment

Profile-to-profile alignment is the core idea

The README describes the HH-suite as an open-source software package for sensitive protein sequence searching based on the pairwise alignment of hidden Markov models. That single clause distinguishes it from ordinary sequence search. Instead of comparing a query sequence against database sequences directly, the query is turned into a profile and the database entries are represented as profiles too, and the comparison happens between two probabilistic models rather than two strings. That is why the tool is described as sensitive: a profile carries the conservation and variation information of a whole family, so a match that would be invisible at the residue level can still score well. The audience is computational biologists, and specifically the people who annotate protein function, where a remote homologue is often the only evidence available for a poorly characterised protein. The project is maintained by Johannes Soeding and colleagues at the Soeding lab, with the paper reference given in the README.

The four install routes and what each one gives you

Installation is unusually well covered, with four options. Conda through conda-forge and bioconda, Docker from the soedinglab/hh-suite image, and two static builds, one for SSE2 and one for AVX2, plus compiling from source. The static builds are a single wget, tar and PATH export.

# install via conda
conda install -c conda-forge -c bioconda hhsuite 
# install docker
docker pull soedinglab/hh-suite
# static SSE2 build
wget https://github.com/soedinglab/hh-suite/releases/download/v3.3.0/hhsuite-3.3.0-SSE2-Linux.tar.gz; tar xvfz hhsuite-3.3.0-SSE2-Linux.tar.gz; export PATH="$(pwd)/bin:$(pwd)/scripts:$PATH"
# static AVX2 build
wget https://github.com/soedinglab/hh-suite/releases/download/v3.3.0/hhsuite-3.3.0-AVX2-Linux.tar.gz; tar xvfz hhsuite-3.3.0-AVX2-Linux.tar.gz; export PATH="$(pwd)/bin:$(pwd)/scripts:$PATH"

There is a hardware caveat attached. HH-suite3 requires a 64-bit system, checked with uname -a | grep x86_64, and on AMD and Intel processors at least the SSE2 instruction set, checked on Linux with cat /proc/cpuinfo | grep sse2 and on macOS with sysctl -a | grep machdep.cpu.features | grep SSE2. The README states that AVX2 is roughly twice as fast as SSE2, and that the suite also works on Linux systems with ARM64 and PPC64LE processors. One exception is stated firmly: only the self-compiled version includes MPI support, since the MPI configuration is specific to the local environment.

Compiling from source, and the macOS OpenMP trap

Building from source needs a recent C or C++ compiler, at least GCC 4.8 or Clang 3.6, and CMake 2.8.12 or later. The sequence clones the repository, makes a build directory, configures with an install prefix pointing at the current directory, builds with make and installs, then puts the bin and scripts directories on the PATH.

git clone https://github.com/soedinglab/hh-suite.git
mkdir -p hh-suite/build && cd hh-suite/build
cmake -DCMAKE_INSTALL_PREFIX=. ..
make -j 4 && make install
export PATH="$(pwd)/bin:$(pwd)/scripts:$PATH"

The macOS note is the part that catches people. The README says the default macOS clang compiler does not support OpenMP, so HH-suite3 will only be able to use a single thread, and the fix is to install the gcc compiler from Homebrew and point CMake at it explicitly.

CC="$(brew --prefix)/bin/gcc-10" CXX="$(brew --prefix)/bin/g++-10" cmake -DCMAKE_INSTALL_PREFIX=. ..

A single-threaded build on a Mac is not a minor inconvenience for a search that is by nature parallel, so this is worth doing before you benchmark anything.

The databases are a separate, larger project

The README lists the databases available for HH-suite3, and this is where a realistic evaluation has to start, because the search is only as good as what it searches. Uniclust30 is one option, BFD is another and consists of 2.5 billion mostly environmental protein sequences, and a bundle of Pfam, SCOP, PDB70 and dbCAN is available from a mirror. A separate set covering COG, ECOG, CD and others is maintained by the MPI Bioinformatics Toolkit, and the repository also links the general databases page for the HH-suite. The scale difference is the point. BFD is two and a half billion sequences, mostly environmental, which is what makes remote homology detection work for unknown organisms, and building a database of that size is a serious undertaking with its own storage and time costs, entirely separate from installing the search tool. That separation is also why the databases live at their own URLs and their own projects rather than inside this repository.

Running HHblits for a search and for an alignment

The usage section is short, and it distinguishes two things people often conflate. A single search iteration of HHblits takes the input file, an output file, a count of one iteration, and the database basename.

hhblits -i <input-file> -o <result-file> -n 1 -d <database-basename>

Generating an alignment of homologous sequences adds the -oa3m option with the result alignment path, which is the step that turns matches into a multiple alignment you can inspect.

hhblits -i <input-file> -o <result-file> -oa3m <result-alignment> -d <database-basename>

The full option list is available by running HHblits with the -h parameter, which is the practical reference. The tool family also includes other programs named in the repository topics, such as hhsearch for pair sequence search, hhpred for fold prediction and hhblits for the iterative profile search, and the README points to an extensive user guide in the project wiki with usage examples, frequently asked questions and guides on building your own databases. The last point matters: the wiki covers database construction, which is the part the README itself cannot cover in a page.

Release cadence, licence and the shape of the repository

The release history is the first thing to notice. The tagged versions are v3.2.0 in April 2019, v3.3.0 in August 2020, and a user guide update in December 2020, with no new numbered release since. The repository is not archived and the last push was on 2026-10-07, so work continues, but the code you get by default is newer than any tagged release, and the static binary downloads still point at v3.3.0. That gap is the main upgrade risk to plan for. The licence is GPL-3.0, which is the usual choice for scientific software that academic and commercial users both run, and it carries the copyleft obligations that implies for derived work. The repository layout is a conventional CMake project with CMakeLists.txt, cmake/, src/, lib/, scripts/, data/ and a Dockerfile, plus an azure-pipelines.yml for the build. The Dockerfile shows the cross-architecture build in detail, with a first stage that downloads qemu static binaries for ppc64le and aarch64, a builder stage installing build-essential, cmake, xxd and ninja, a cmake invocation with -DHAVE_SSE2=1 and a Release build type, and a final slim Debian stage that installs libstdc++6 and libgomp1 and sets HHLIB and PATH.

Where HH-suite3 is the wrong tool

The boundaries are worth naming. If you need genome-scale search, HH-suite3 is not the right engine, because the sensitivity it buys comes from profiles and from the scale of the profile database, and a tool built around profile-to-profile comparison is a different trade from one built around k-mer indexing. If your query is a single sequence with no profile and you want a fast hit list against a large sequence database, the profile machinery is overhead. If you do not have the database and the disk and the patience to build one, the tool is not usable out of the box, and the README is honest that the databases are separate. There is also the maintenance reality: no tagged release since 2020 means you are running either a static binary from that era or an untagged master, and the MPI support exists only in a build you compile yourself, which is a constraint for anyone trying to run the tool across a cluster. The alternative worth naming is a different profile-based searcher from the same lab's ecosystem, MMseqs2, which shares the same database format and the same authors and takes a different approach to the speed and sensitivity trade. The honest comparison is that HH-suite3 is the more sensitive option for hard remote homology cases, and the more demanding one in every other respect.

Editorial conclusion

Adopt HH-suite3 if you need remote homology detection or deep protein annotation and already have a sequence database to search, since the tool is the search engine and the databases are a separate project. Do not adopt it expecting a one-command database pipeline, because building Uniclust30 or BFD is a separate undertaking. Verify first that your processor has at least SSE2, that your chosen static build matches your instruction set, and that you read the MPI caveat, since only a self-compiled version keeps parallel support.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. Releases
5. soedinglab/hh-suite on GitHub