vsearch

VSEARCH

Introduction

The aim of this project is to create an alternative to the USEARCH tool developed by Robert C. Edgar (2010). The new tool should:

• have open source code with an appropriate open source license
• be free of charge, gratis
• have a 64-bit design that handles very large databases and much more than 4GB of memory
• be as accurate or more accurate than usearch
• be as fast or faster than usearch

We have implemented a tool called VSEARCH which supports de novo and reference based chimera detection, clustering, full-length and prefix dereplication, rereplication, reverse complementation, masking, all-vs-all pairwise global alignment, exact and global alignment searching, shuffling, subsampling and sorting. It also supports FASTQ file analysis, filtering, conversion and merging of paired-end reads.

VSEARCH stands for vectorized search, as the tool takes advantage of parallelism in the form of SIMD vectorization as well as multiple threads to perform accurate alignments at high speed. VSEARCH uses an optimal global aligner (full dynamic programming Needleman-Wunsch), in contrast to USEARCH which by default uses a heuristic seed and extend aligner. This usually results in more accurate alignments and overall improved sensitivity (recall) with VSEARCH, especially for alignments with gaps.

VSEARCH binaries are provided for GNU/Linux on five 64-bit processor architectures: x86_64, POWER8 (ppc64le), ARMv8 (aarch64), little-endian 64-bit RISC-V (riscv64), and little-endian 64-bit MIPS (mips64el). Binaries are also provided for macOS (version 10.9 Mavericks or later) on Intel (x86_64) and Apple Silicon (ARMv8), as well as Windows (64-bit, version 7 or higher, on x86_64). VSEARCH contains native SIMD code for three processor architectures (SSE2/SSSE3, AltiVec/VMX/VSX, Neon). In addition, VSEARCH uses the SIMD Everywhere (SIMDe) library to enable building on riscv64, mips64el, and other little-endian architectures, but the performance may be lower than a native implementation.

Various packages, plugins and wrappers for VSEARCH are also available from other sources - see below.

The source code compiles correctly with gcc (versions 4.8.5 to 14.0) and llvm-clang (3.8 to 19.0). The source code should also compile on FreeBSD and NetBSD systems.

VSEARCH can directly read input query and database files that are compressed using gzip (.gz) and bzip2 (.bz2) if the zlib and bzip2 libraries are available.

Most of the nucleotide based commands and options in USEARCH version 7 are supported, as well as some in version 8. The same option names as in USEARCH version 7 has been used in order to make VSEARCH an almost drop-in replacement. VSEARCH does not support amino acid sequences or local alignments. These features may be added in the future.

Getting Help

If you can’t find an answer in online documentation, or in the manual pages installed by make install (start with man vsearch), please visit the VSEARCH Web Forum to post a question or start a discussion.

Example

In the example below, VSEARCH will identify sequences in the file database.fsa that are at least 90% identical on the plus strand to the query sequences in the file queries.fsa and write the results to the file alnout.txt.

./vsearch --usearch_global queries.fsa --db database.fsa --id 0.9 --alnout alnout.txt

Download and install

Source distribution To download the source distribution from a release and build the executable and the documentation, use the following commands:

wget https://github.com/torognes/vsearch/releases/download/v2.32.0/vsearch-2.32.0.tar.gz
tar xzf vsearch-2.32.0.tar.gz
cd vsearch-2.32.0
./configure CFLAGS="-O3" CXXFLAGS="-O3"
make ARFLAGS="cr"
sudo make install

You may customize the installation directory using the --prefix=DIR option to configure. If the compression libraries zlib and/or bzip2 are installed on the system, they will be detected automatically and support for compressed files will be included in vsearch (see section Dependencies below). Support for compressed files may be disabled using the --disable-zlib and --disable-bzip2 options to configure. The manual pages are generated from markdown sources with pandoc: a release tarball ships them ready-made and needs no pandoc, while building them from a git checkout does. configure reports whether it found pandoc, and a build without it simply produces no manual (--disable-manpages asks for that explicitly). It is recommended to run configure with the options CFLAGS="-O3" and CXXFLAGS="-O3". Other options may also be applied to configure, please run configure -h to see them all. The GCC C++ (g++) compiler (or clang) and make are required to build vsearch. The source distribution above ships the generated build files (configure, Makefile.in, …), so GNU autoconf and automake are not needed to build it. They are needed to build from a git checkout, which does not track those files: run ./autogen.sh first (autoconf version 2.63 or later), as shown below. The same applies after modifying configure.ac or a Makefile.am. Version 3.82 or later of make may be required on Linux, while version 3.81 is sufficient on macOS.

Out-of-tree (VPATH) builds configure and make may be run from a separate, initially empty directory instead of the source tree. All object files, libraries and the final binary are then written under that build directory, leaving the source tree pristine, and several builds (for example debug and release, or different cross-compilation targets) can coexist from a single checkout:

mkdir build && cd build
../configure CFLAGS="-O3" CXXFLAGS="-O3"
make ARFLAGS="cr"

To build VSEARCH on Debian and similar Linux distributions (Ubuntu etc) you’ll need the following packages: autoconf, automake, g++, libbz2-dev, make, zlib1g-dev. Include libsimde-dev to build on riscv64 or mips64el.

To build VSEARCH on Fedora and similar Linux distributions (RHEL, Centos etc) you’ll need the following packages: autoconf, automake, bzip2-devel, gcc-c++, make, zlib-devel.

Of these, autoconf and automake are needed to build from a git checkout, which generates the build system with ./autogen.sh, and after editing configure.ac or a Makefile.am. A build from the source distribution does not require them, since it ships the generated files.

Instead of downloading the source distribution as a compressed archive, you could clone the repo and build it as shown below. The options to configure as described above are still valid.

git clone https://github.com/torognes/vsearch.git
cd vsearch
./autogen.sh
./configure CFLAGS="-O3" CXXFLAGS="-O3"
make ARFLAGS="cr"
sudo make install

Binary distribution: Starting with version 1.4.0, binary distribution files containing pre-compiled binaries as well as the documentation will be made available as part of each release. The included executables include support for input files compressed by zlib and bzip2 (with files usually ending in .gz or .bz2).

Binary distributions are provided for x86-64 systems running GNU/Linux, macOS (version 10.7 or higher) or Windows (64-bit, version 7 or higher), 64-bit AMDv8 (aarch64) systems running GNU/Linux or macOS, as well as POWER8 (ppc64le), 64-bit little-endian RISC-V (risv64), and 64-bit little endian MIPS (mips64el) systems running GNU/Linux. A universal macOS binary is also provided. In addition, an x86_64 binary built for the discontinued RHEL 7 and CentOS 7 linux distributions is provided. The other Linux binaries are built on Debian 11 (oldoldstable, Bullseye). Binaries whose name ends in -static are available for all Linux architectures except x86_64: they carry the C++ runtime (libstdc++/libgcc) inside the executable, so they run on systems whose own C++ runtime is older than the one they were built with. They still use the system C library, and the compression libraries are still loaded at run time, so they read gzip and bzip2 input like every other binary. The Windows binary was built with cross compilation using Mingw-w64.

Download the appropriate executable for your system using the following commands if you are using a Linux or macOS system:

wget https://github.com/torognes/vsearch/releases/download/v{VERSION}/vsearch-{VERSION}-{OS}-{ARCH}.tar.gz
tar xzf vsearch-{VERSION}-{OS}-{ARCH}.tar.gz

Replace {VERSION} with the VSEARCH version number (e.g. 2.32.0), {OS} with the target operating system (linux or macos), and {ARCH} with the architecture (x86_64, aarch64, ppc64le, riscv64, or mips64el). You could add -static after {ARCH} to get a statically compiled version for Linux (except x86_64). The name of the binary for the RHEL 7 and CentOS 7 Linux distributions ends in -ubi7.

Or, if you are using Windows, download and extract (unzip) the contents of this file:

https://github.com/torognes/vsearch/releases/download/v{VERSION}/vsearch-{VERSION}-win-x86_64.zip

Linux and Mac: You will now have the binary distribution in a folder called vsearch-{VERSION}-{OS}-{ARCH} in which you will find three subfolders bin, man and completion. We recommend making a copy or a symbolic link to the vsearch binary bin/vsearch in a folder included in your $PATH, and copies or symbolic links to the contents of man (the man1, man5 and man7 subfolders) in a folder included in your $MANPATH. The completion folder holds the shell auto-completion scripts; see Shell auto-completion below for where to put them.

Windows: You will now have the binary distribution in a folder called vsearch-{VERSION}-win-x86_64. The vsearch executable is called vsearch.exe. If you want to be able to call vsearch.exe from any command prompt window, you can put the VSEARCH executable in a folder (for instance C:\Users\<yourname>\bin), and add the new folder to the user Path: open the Environment Variables window by searching for it in the Start menu, Edit user variables, add ;C:\Users\<yourname>\bin to the end of the Path variable, and save your changes. The windows distribution also includes the libbz2.dll and zlib1.dll files required for reading compressed input files. These DLL’s have been obtained for mingw-w64 from the MSYS2 platform.

Documentation: The VSEARCH user’s manual is a set of manual pages: a hub page listing every command, one page per command, one page per file format, and one page per reference topic. make install installs them all; type man vsearch for the hub, man vsearch-usearch_global for a command, man 5 vsearch-fastq for a file format, and man 7 vsearch-userfields for a reference topic. They are also readable online, and they come with the binary distribution. To install them manually, copy the pages, or create symbolic links to them, in the man1, man5 and man7 subfolders of a folder included in your $MANPATH. Being generated, the pages themselves are not in git: they are built from the markdown sources in man, which is where a documentation change belongs, and rebuilt with make -C man regenerate-manpages. The release history is one of those pages, man 7 vsearch-history, and is installed as a plain-text NEWS file as well.

Shell auto-completion

VSEARCH ships completion scripts for bash, zsh and fish, in the completion folder. Once installed, pressing the Tab key while typing a vsearch command line suggests the available commands; once a command is on the line, only the options that this command accepts are offered, values are suggested for options that take a fixed set (--qmask, --dbmask, --strand), and options expecting a file name complete file names, filtered by extension where that makes sense.

make install installs all three, in the standard locations for each shell ($PREFIX/share/bash-completion/completions, $PREFIX/share/zsh/site-functions and $PREFIX/share/fish/vendor_completions.d). Distributions that place them elsewhere can say so at configure time, and --disable-completion skips them entirely:

./configure --with-bashcompdir=/etc/bash_completion.d
./configure --disable-completion

From the binary distribution, or to enable completion for a single user without installing system-wide, copy the file your shell needs (or create a symbolic link to it) from the completion folder:

# bash
cp completion/vsearch ~/.local/share/bash-completion/completions/vsearch

# zsh: any directory in your $fpath will do
mkdir -p ~/.zsh/completions && cp completion/_vsearch ~/.zsh/completions/

# fish
cp completion/vsearch.fish ~/.config/fish/completions/

For zsh, the directory has to be in $fpath before compinit runs, because compinit scans $fpath at the moment it is called and not later. In ~/.zshrc:

fpath=(~/.zsh/completions $fpath)
autoload -Uz compinit && compinit

If completion still does not appear after that, ~/.zcompdump is probably a stale cache: rm -f ~/.zcompdump* and start a new shell.

For bash, sourcing the file from ~/.bashrc works too (source /path/to/completion/vsearch). The script uses the bash-completion package’s filename completion when it is installed, and falls back to its own when it is not, so neither path requires it.

The three scripts are generated from a single specification of vsearch’s command-line interface, completion/spec/vsearch.yaml, which is where a completion change belongs; make check verifies that the specification still matches the option tables in the source, so completion cannot silently fall behind the program. See completion/README.md for details.

API

Thanks to Daniel McDonald (with help from Anthropic’s Claude) there is now an API to many of VSEARCH’s core functions. You can build a static library libvsearch.a and link it directly with your own code. Please see the Library API Examples and the main API header file for details. The API is currently at version 0.17.0 and may change quite a bit in the beginning.

Packages, plugins, and wrappers

Conda package Thanks to the BioConda team, there is now a vsearch package in Conda.

Debian package Thanks to the Debian Med team, there is now a vsearch package in Debian.

FreeBSD ports package Thanks to Jason Bacon, a vsearch FreeBSD ports package is available. Install the binary package with pkg install vsearch, or build from source with additional optimizations.

Galaxy wrapper Thanks to the work of the Intergalactic Utilities Commission members, VSEARCH is now part of the Galaxy ToolShed.

Homebrew package Thanks to Torsten Seeman, a vsearch package for Homebrew has been made.

Pkgsrc package Thanks to Jason Bacon, a vsearch pkgsrc package is available for NetBSD and other UNIX-like systems. Install the binary package with pkgin install vsearch, or build from source with additional optimizations.

QIIME 2 plugin Thanks to the QIIME 2 team, there is now a plugin called q2-vsearch for QIIME 2.

Rsearch R package Thanks to Cassandra Stamsaas and colleagues, there is now an R package called Rsearch offering a user-friendly interface to VSEARCH from within R, with additional visualization and parameter tuning tools (Stamsaas et al. 2026).

Converting output to a biom file for use in QIIME and other software

With the from-uccommand in biom 2.1.5 or later, it is possible to convert data in a .uc file produced by vsearch into a biom file that can be read by QIIME and other software. It is described here.

Please note that VSEARCH version 2.2.0 and later are able to directly output OTU tables in biom 1.0 format as well as the classic and mothur formats.

Implementation details and initial assessment

Please see the paper for details:

Rognes T, Flouri T, Nichols B, Quince C, Mahé F. (2016) VSEARCH: a versatile open source tool for metagenomics. PeerJ 4:e2584 doi: 10.7717/peerj.2584

Dependencies

Compiling VSEARCH requires either GCC (g++) or clang and make. The autotools (autoconf/automake) are not needed to build the source distribution, which ships the generated build files, and are required to build from a git checkout, which generates them with ./autogen.sh. Optionally, the header files for the following two optional libraries are required if support for gzip and bzip2 compressed FASTA and FASTQ input files is needed:

• libz (zlib library) (zlib.h header file, available as zlib1g-dev on Debian-based distributions) (optional)
• libbz2 (bzip2lib library) (bzlib.h header file, available as libbz2-devon Debian-based distributions) (optional)

VSEARCH will automatically check whether these libraries are available and load them dynamically.

On Windows these libraries are called zlib1.dll and libbz2.dll. These DLL’s are included with the released distribution of vsearch 2.27.0 and later.

VSEARCH license and third party licenses

The VSEARCH code is dual-licensed either under the GNU General Public License version 3 or under the BSD 2-clause license. Please see LICENSE.txt for details.

VSEARCH includes code from several other projects. We thank the authors for making their source code available.

VSEARCH includes code from Google’s CityHash project by Geoff Pike and Jyrki Alakuijala, providing some excellent hash functions available under a MIT license.

VSEARCH includes code derived from Tatusov and Lipman’s DUST program that is in the public domain.

VSEARCH includes public domain code written by Alexander Peslyak for the MD5 message digest algorithm.

VSEARCH includes public domain code written by Steve Reid and others for the SHA1 message digest algorithm.

The VSEARCH distribution includes code from GNU Autoconf which normally is available under the GNU General Public License, but may be distributed with the special autoconf configure script exception.

VSEARCH may include code from the zlib library copyright Jean-loup Gailly and Mark Adler, distributed under the zlib license.

VSEARCH may include code from the bzip2 library copyright Julian R. Seward, distributed under a BSD-style license.

Code

The code is written mostly in C++.

VSEARCH may be compiled with zlib or bzip2 integration that allows it to read compressed FASTA files. The zlib and the bzip2 libraries are needed for this.

Bugs

All bug reports are highly appreciated. You may submit a bug report here on GitHub as an issue (preferred), you could post a message on the VSEARCH Web Forum or you could send an email to [email protected].

Limitations

VSEARCH is designed for rather short sequences, and will be slow when sequences are longer than about 5,000 bp. This is because it always performs optimal global alignment on selected sequences.

The VSEARCH team

The main contributors to VSEARCH:

• Torbjørn Rognes [email protected] (Coding, testing, documentation, evaluation)
• Frédéric Mahé [email protected] (Documentation, testing, coding, feature suggestions)
• Tomáš Flouri [email protected] (Coding, testing)
• Christopher Quince [email protected] (Initiator, feature suggestions, evaluation)
• Ben Nichols [email protected] (Evaluation)

Acknowledgements

Special thanks to the following people for patches, suggestions, computer access etc:

• Davide Albanese
• Colin Brislawn
• Michael R. Crusoe
• Jeff Epler
• Daniel McDonald
• Christopher M. Sullivan
• Andreas Tille
• Sarah Westcott

Citing VSEARCH

Please cite the following publication if you use VSEARCH:

Rognes T, Flouri T, Nichols B, Quince C, Mahé F. (2016) VSEARCH: a versatile open source tool for metagenomics. PeerJ 4:e2584. doi: 10.7717/peerj.2584

Please note that citing any of the underlying algorithms, e.g. UCHIME, may also be appropriate.

Test datasets

Test datasets (found in the separate vsearch-data repository) were obtained from the BioMarks project (Logares et al. 2014), the TARA OCEANS project (Karsenti et al. 2011) and the Protist Ribosomal Reference Database (PR²) (Guillou et al. 2013).

References

• Edgar RC (2010) Search and clustering orders of magnitude faster than BLAST. Bioinformatics, 26 (19): 2460-2461. doi:10.1093/bioinformatics/btq461

• Edgar RC (2016) SINTAX: a simple non-Bayesian taxonomy classifier for 16S and ITS sequences. bioRxiv. doi:10.1101/074161

• Edgar RC (2016) UNOISE2: improved error-correction for Illumina 16S and ITS amplicon sequencing. bioRxiv. doi:10.1101/081257

• Edgar RC, Flyvbjerg H (2015) Error filtering, pair assembly and error correction for next-generation sequencing reads. Bioinformatics, 31 (21): 3476-3482. doi:10.1093/bioinformatics/btv401

• Edgar RC, Haas BJ, Clemente JC, Quince C, Knight R (2011) UCHIME improves sensitivity and speed of chimera detection. Bioinformatics, 27 (16): 2194-2200. doi:10.1093/bioinformatics/btr381

• Guillou L, Bachar D, Audic S, Bass D, Berney C, Bittner L, Boutte C, Burgaud G, de Vargas C, Decelle J, del Campo J, Dolan J, Dunthorn M, Edvardsen B, Holzmann M, Kooistra W, Lara E, Lebescot N, Logares R, Mahé F, Massana R, Montresor M, Morard R, Not F, Pawlowski J, Probert I, Sauvadet A-L, Siano R, Stoeck T, Vaulot D, Zimmermann P & Christen R (2013) The Protist Ribosomal Reference database (PR2): a catalog of unicellular eukaryote Small Sub-Unit rRNA sequences with curated taxonomy. Nucleic Acids Research, 41 (D1), D597-D604. doi:10.1093/nar/gks1160

• Karsenti E, González Acinas S, Bork P, Bowler C, de Vargas C, Raes J, Sullivan M B, Arendt D, Benzoni F, Claverie J-M, Follows M, Jaillon O, Gorsky G, Hingamp P, Iudicone D, Kandels-Lewis S, Krzic U, Not F, Ogata H, Pesant S, Reynaud E G, Sardet C, Sieracki M E, Speich S, Velayoudon D, Weissenbach J, Wincker P & the Tara Oceans Consortium (2011) A holistic approach to marine eco-systems biology. PLoS Biology, 9(10), e1001177. doi:10.1371/journal.pbio.1001177

• Logares R, Audic S, Bass D, Bittner L, Boutte C, Christen R, Claverie J-M, Decelle J, Dolan J R, Dunthorn M, Edvardsen B, Gobet A, Kooistra W H C F, Mahé F, Not F, Ogata H, Pawlowski J, Pernice M C, Romac S, Shalchian-Tabrizi K, Simon N, Stoeck T, Santini S, Siano R, Wincker P, Zingone A, Richards T, de Vargas C & Massana R (2014) The patterning of rare and abundant community assemblages in coastal marine-planktonic microbial eukaryotes. Current Biology, 24(8), 813-821. doi:10.1016/j.cub.2014.02.050

• Rognes T (2011) Faster Smith-Waterman database searches by inter-sequence SIMD parallelisation. BMC Bioinformatics, 12: 221. doi:10.1186/1471-2105-12-221

• Stamsaas C, Rognes T, Rudi K, Snipen L, Vinje H (2026) Rsearch: An R interface to VSEARCH supporting visualization and parameter tuning. bioRxiv. doi:10.64898/2026.09.10.750626