Install Nextstrain

Nextstrain is a collection of different tools including:

  • Augur: a bioinformatics toolkit for the analysis of pathogen genomes

  • Auspice: a tool for interactive visualization of pathogen evolution

  • Nextstrain command line interface (CLI): tools for management of analysis workflows and environments

The following instructions describe how to install these tools with Conda or Docker. For more details, see the high level overview of these different components.

Note

If you want to contribute to the development of Nextstrain tools, see the developer documentation for instructions to install these tools from source.

If you prefer to manage your own custom environment (e.g., a Conda environment, Docker image, environment modules on a cluster, etc.), see the individual installation documentation for Nextstrain CLI, Augur, or Auspice.

Install Conda

Conda is a package and environment management system that allows you to install Python and other software into controlled environments without disrupting other software you have installed (e.g., on your computer, your shared cluster, etc.). Conda provides an appropriate version of Python required by all approaches to installing Nextstrain tools.

Note

If you use Microsoft Windows, install the Windows Subsystem for Linux (WSL). Follow instructions to open a new WSL window for your Linux distribution and then run the following commands.

Install Miniconda with Python 3 for your operating system and then update Conda to the latest version.

conda update -n base conda

Install Nextstrain with Conda or Docker

Next, decide whether you prefer to install Nextstrain with Conda or Docker. We recommend Conda for M1 Mac and Windows users. Docker is not yet ready for widespread use on the M1 Mac. Similarly, there are still significant obstacles to running Docker with Windows, as documented in our issue tracking the problems.

Create a Conda environment named nextstrain. This command will install Nextstrain and its dependencies.

conda create -n nextstrain -c conda-forge -c bioconda \
  augur auspice nextstrain-cli nextalign snakemake awscli git pip

Confirm that the installation worked.

conda activate nextstrain
nextstrain check-setup --set-default

The final output from the last command should look like this:

Setting default environment to native.

Whenever you open a new terminal window to work on a Nextstrain analysis, remember to activate the Nextstrain Conda environment with conda activate nextstrain. Next, check out the quickstart.

Upgrade an existing installation

Update the base Conda environment.

conda update -n base conda

Update the Nextstrain environment.

conda activate nextstrain
conda update --all

Troubleshoot a broken installation

If Conda fails to install or update Nextstrain using the commands above, it’s possible that Conda itself is out-of-date or that Conda cannot figure out how to resolve the environment’s dependencies. Try the following approaches, to fix these broken installations.

Remove your environment and start from scratch

Starting from scratch often fixes problems with Conda environments. To start over with a new Nextstrain environment, delete your current environment.

conda activate base
conda env remove -n nextstrain

Then, repeat the installation instructions above, starting with the update of Conda itself.

Use Mamba as an alternative to Conda’s environment solver

Mamba is a drop-in replacement for most conda functionality that implements a faster dependency solving algorithm in C++ and multithreaded downloads. As a result, Mamba can install Conda packages much faster and more accurately than the original Conda installer.

To try it out, install Mamba.

conda install -n base -c conda-forge mamba

Then, use Mamba to create the Nextstrain environment.

mamba create -n nextstrain -c conda-forge -c bioconda \
  augur auspice nextstrain-cli nextalign snakemake awscli git pip

Similarly, use Mamba to update an existing Nextstrain environment to the latest versions of its tools.

conda activate nextstrain
mamba update --all