Installing Nextstrain

Hint

Before installing, we recommend you read about the parts of Nextstrain.

The following instructions describe how to install Nextstrain’s software tools, including:

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

  • Auspice: a tool for interactive visualization of pathogen evolution

  • Nextstrain CLI: tools for management of analysis workflows and environments

Note

If you want to contribute to the development of Nextstrain or 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, and Auspice.

Background

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. Miniconda is the minimal installation of the command-line interface to conda.

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.

Docker is a container system freely-available for all platforms. When you use Docker to run Nextstrain components, you don’t need to manage any other Nextstrain software dependencies as validated versions are already bundled into a container image by the Nextstrain team.

Installation Steps

These instructions will install the Nextstrain CLI and tools to run and view your own Nextstrain analyses. Configuration options vary by operating system.

Note

If you are an experienced user, you can replace conda with pip but note the extra installation steps for Augur and install Auspice via npm.

  1. Install Miniconda:

    1. Go to the installation page.

    2. Scroll down to the Latest Miniconda Installer Links section and click the MacOSX platform link that ends with pkg.

    3. Open the downloaded file and follow through installation prompts.

  2. Open a terminal window.

  3. Install mamba on the base conda environment:

    conda install -n base -c conda-forge mamba --yes
    conda activate base
    
  4. Install the Nextstrain components. There are two options:

    Warning

    If using a newer Mac with an Apple silicon chip (e.g. M1), Native installation is recommended due to slowness with the Docker installation. We are considering ways to improve this.

    1. Install Docker Desktop using the official guide.

    2. Create a conda environment named nextstrain and install the Nextstrain CLI:

      mamba create -n nextstrain -c conda-forge -c bioconda nextstrain-cli --yes
      
    3. Activate the conda environment:

      conda activate nextstrain
      
  5. Confirm that the installation worked.

    nextstrain check-setup --set-default
    

    The final output from the last command should look like this, where <option> is the option chosen in the previous step:

    Setting default environment to <option>.
    

Optionally, configure AWS Batch if you’d like to run nextstrain build on AWS.

Next, try Running a pathogen workflow.

Note

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

Update an existing installation

Update the nextstrain conda environment.

mamba update -n base conda mamba
conda activate nextstrain
mamba update --all -c conda-forge -c bioconda

[Docker] Download the latest image with the Nextstrain CLI.

nextstrain update

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.

Next steps

With Nextstrain installed, try Running a pathogen workflow next.