Skip to contents

Setting up DIAMOND2 and BLAST+ on Windows

2026-10-19

Source: vignettes/setup_windows.Rmd
setup_windows.Rmd

Getting Started

DIAMOND2 and BLAST+ are external executables that orthologr shells out to (e.g. diamond(), deepclust(), deepclust_realign(), blast(), blast_best(), blast_rec()). Neither is an R package, so on Windows both must be installed separately and made discoverable to R before these interface functions can be used. See the Install vignette for general installation instructions across platforms.

This vignette focuses on Windows, and describes the quickest way to make both tools discoverable for a single R session without touching your system-wide configuration: temporarily adding their folders to PATH.

Install Rtools

This section is about building orthologr itself, not about DIAMOND2 or BLAST+. orthologr ships compiled C++ code (used, for example, by gestimator()), so installing it from source on Windows — via install.packages(), devtools::install_github(), or devtools::load_all() — may require a working compiler toolchain. Windows does not include one by default, so you need to install Rtools.

  1. Check your R version (R.version.string) and download the matching Rtools installer from the CRAN Rtools page (e.g. Rtools45 for R 4.5.x).
  2. Run the installer with default settings.
  3. Restart RStudio.
  4. Verify the toolchain is available:
pkgbuild::check_build_tools(debug = TRUE)
Sys.which("make")

If make resolves to an empty string, or pkgbuild::has_build_tools() returns FALSE, Rtools was not installed correctly (a common cause is an interrupted or incomplete installer run, which can leave an empty c:\rtoolsNN folder despite PATH being set correctly) — reinstall Rtools before continuing.

Once Rtools is confirmed working, devtools::load_all() and R CMD INSTALL should be able to compile orthologr’s C++ sources.

Install DIAMOND2 with diamond_install()

The simplest way to get DIAMOND2 on Windows is to let orthologr download it for you. This avoids manually unzipping diamond.exe, choosing a folder, and editing PATH:

diamond_install() downloads diamond-windows.zip from the official DIAMOND2 releases, extracts diamond.exe into the R user cache folder and checks that it runs. No administrator rights are needed. Windows has no ARM build upstream, so on Windows on ARM please install DIAMOND2 manually (see the sections below).

You can see where the binary was placed, and which copy orthologr will use, with:

tools::R_user_dir("orthologr", which = "cache")  # cache folder; diamond.exe is in the "diamond" subfolder
diamond_path()                                   # NULL if diamond is on the PATH, otherwise the cache folder

diamond(), diamond_best(), diamond_rec(), set_diamond(), deepclust() and deepclust_realign() use this copy automatically when path = NULL and no diamond is found on your PATH. A diamond.exe on your PATH always takes precedence. You can also pass the cache folder explicitly:

diamond(
  query_file   = system.file("seqs/ortho_thal_cds.fasta", package = "orthologr"),
  subject_file = system.file("seqs/ortho_lyra_cds.fasta", package = "orthologr"),
  path         = diamond_install(quiet = TRUE)  # returns the folder containing diamond.exe
)

Troubleshooting:

  • If the download fails (e.g. behind a corporate proxy or firewall), download diamond-windows.zip manually from the releases page and continue with the manual steps below.
  • If Windows Defender or another antivirus quarantines diamond.exe, restore it or add the cache folder as an exception, then run diamond_install(force = TRUE).
  • diamond_install() only installs DIAMOND2. BLAST+ still has to be installed manually, see the Install vignette.
  • To update DIAMOND2, run diamond_install(force = TRUE); to pin a release, use e.g. diamond_install(version = "v2.1.9", force = TRUE).

See also the Install DIAMOND2 section of the Install vignette. If you use diamond_install(), you can skip the following steps for DIAMOND2 and only configure BLAST+.

Confirm the location of the executables

Before doing anything else, confirm that diamond.exe and blastp.exe actually exist where you expect them. Example locations:

C:/Users/<you>/Desktop/R_projects/installations/diamond.exe
C:/Program Files/NCBI/blast-2.17.0+/bin/blastp.exe
file.exists("C:/Users/<you>/Desktop/R_projects/installations/diamond.exe")
file.exists("C:/Program Files/NCBI/blast-2.17.0+/bin/blastp.exe")

If DIAMOND2 or BLAST+ is not yet installed, see the Install vignette for download links.

Set PATH for the current R session (temporary)

This option adds each tool’s folder to the PATH environment variable for the duration of the current R session only. It’s useful for one-off scripts without changing any system settings, and it avoids having to pass a path argument to every orthologr function call.

Sys.setenv(
  PATH = paste(
    "C:/Users/<you>/Desktop/R_projects/installations",
    "C:/Program Files/NCBI/blast-2.17.0+/bin",
    Sys.getenv("PATH"),
    sep = ";"
  )
)

This change is lost as soon as the R session ends, so you’ll need to re-run it every time you start a new session (e.g. by adding it to a project .Rprofile).

Verify the installation 

Sys.which("diamond")
Sys.which("blastp")

Both should now return the full path to the executable instead of "". You can additionally confirm that orthologr itself detects both tools:

is_installed_diamond()
is_installed_blast()
[1] TRUE
[1] TRUE

Additional information

orthologr‘s interface functions (diamond(), deepclust(), deepclust_realign(), blast(), blast_best(), blast_rec(), and their underlying is_installed_*() checks) accept a path argument for cases where you don’t want to rely on PATH at all. Internally these functions now call normalizePath() on any supplied path, so relative paths (e.g. path = "../installations") resolve correctly on Windows — this previously failed because Windows’ system() could not resolve relative executable paths.

This fix applies to both DIAMOND2 and BLAST+: is_installed_blast() (used internally by blast(), blast_best(), and blast_rec()) now uses the same file.path()-based approach, so passing a path argument works correctly on Windows. If you prefer not to pass path every call, you can make blastp permanently discoverable by adding the BLAST+ bin folder to the persistent Windows PATH:

  1. Get the absolute path to the folder containing blastp.exe, e.g. C:\Program Files\NCBI\blast-2.17.0+\bin.
  2. Open Start Menu → “Edit the system environment variables”.
  3. Click Environment Variables….
  4. Under User variables (or System variables for all users), select Path and click Edit….
  5. Click New and paste the absolute folder path (no trailing backslash, no filename — just the directory).
  6. Click OK on all dialogs to save, then restart RStudio (environment variable changes aren’t picked up by already-running processes).
  7. Verify with Sys.which("blastp").

The same persistent approach also works for DIAMOND2, and is preferable to the temporary session-only option if you use orthologr regularly.