Installing Nextstrain

Hint

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

The following instructions describe how to install the full suite of Nextstrain’s software tools, including:

Augur, for bioinformatic analysis of pathogen genomes

Auspice, for interactive visualization of pathogen evolution

Nextstrain CLI, for management of analysis workflows and environments

When completed, you’ll be ready to run Nextstrain workflows.

Installation steps

Steps vary by runtime option (Docker, Conda, ambient) and operating system (macOS, Windows, WSL on Windows, Linux). For help choosing, refer to our Frequently Asked Questions (FAQ), such as:

What are Docker, Conda, Mamba, WSL, etc.?

Should I choose the Docker, Conda, or ambient runtime?

What happened to the “native” runtime?

When should I use (or not use) WSL on Windows?

First, install Nextstrain CLI.

In a Terminal, run:

curl -fsSL --proto '=https' https://nextstrain.org/cli/installer/mac | bash

You can launch a Terminal by clicking the Launchpad icon in the Dock, typing terminal in the search field, and clicking Terminal.

Note

On newer Macs with an Apple silicon chip (e.g. M1), Rosetta 2 is required for both Nextstrain CLI itself and our runtimes. Most of the time, Rosetta 2 will already be enabled. If not, the installer will ask you to first enable Rosetta 2 and then retry the installation.

In a PowerShell terminal, run:

Invoke-RestMethod https://nextstrain.org/cli/installer/windows | Invoke-Expression

You can launch a PowerShell terminal by clicking the Start menu, typing powershell, and pressing enter. Make sure to choose the item that is not marked “(Adminstrator)”.

Install Windows Subsystem for Linux (WSL) 2. You may have to restart your machine when configuring WSL.

In a WSL terminal, run:

curl -fsSL --proto '=https' https://nextstrain.org/cli/installer/linux | bash

You can launch a WSL terminal by clicking the Start menu, typing wsl, and pressing enter.

In a terminal, run:

curl -fsSL --proto '=https' https://nextstrain.org/cli/installer/linux | bash

You can launch a terminal by clicking the “Show applications” icon in the Dock, typing terminal in the search field, and clicking Terminal.

Make sure to follow the installer’s final instructions to setup your shell config.

Then, install a Nextstrain runtime.

Set up the runtime:

nextstrain setup --set-default conda

Set up the runtime:

nextstrain setup --set-default conda

Set up the runtime:

nextstrain setup --set-default conda

Note

The ambient runtime does not require a particular installation method; it will work as long as the programs required by Nextstrain are available. The following describes how to accomplish this using a custom Conda environment as an example.

If you already have Conda or Mamba installed and use it for other projects, you may need to adjust the instructions below.

Install the necessary programs into a custom Conda environment you manage.

Install Miniconda:
1. Download the installer.
  
  Note
  
  This is the Intel x86 64-bit installer, which we recommend even for Mac computers with Apple silicon (e.g. M1).
2. Open the downloaded file and follow through installation prompts.
Open a new terminal window.

Install Mamba on the base Conda environment:

conda install -n base -c conda-forge mamba --yes
conda activate base

Create a custom Conda environment named nextstrain:

# Create and activate a "nextstrain" environment
mamba create -n nextstrain
conda activate nextstrain

# Configure software channels; order is important!
conda config --env --add channels defaults
conda config --env --add channels bioconda
conda config --env --add channels conda-forge
conda config --env --set channel_priority strict

Install all the necessary software:

mamba install --yes \
    augur auspice nextalign nextclade \
    snakemake git epiweeks pangolin pangolearn

Install Miniconda:

wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh
# follow through installation prompts
rm Miniconda3-latest-Linux-x86_64.sh

Install Mamba on the base Conda environment:

conda install -n base -c conda-forge mamba --yes
conda activate base

Create a custom Conda environment named nextstrain:

# Create and activate a "nextstrain" environment
mamba create -n nextstrain
conda activate nextstrain

# Configure software channels; order is important!
conda config --env --add channels defaults
conda config --env --add channels bioconda
conda config --env --add channels conda-forge
conda config --env --set channel_priority strict

Install all the necessary software:

mamba install --yes \
    augur auspice nextalign nextclade \
    snakemake git epiweeks pangolin pangolearn

For WSL on Windows installs

By default, your Windows home directory will not be directly accessible under your WSL home directory. When run in a WSL prompt, the following command fixes that by creating a symlink to it in your WSL home directory. This allows you to use Windows-based text editors and Linux commands all on the same files.

ln -ws "$(wslpath "$(wslvar USERPROFILE)")" ~/windows_home

Optionally, you can customize the windows_home folder name or only link to a specific directory under your windows user (e.g. ln -ws "$(wslpath "$(wslvar USERPROFILE)")/Documents" ~/windows_documents).

If the command does not work, you may have to first run sudo apt install wslu.

Note

Steps for other Linux distributions (Debian, CentOS, RHEL, etc.) should be identical or very similar.

Install Miniconda:

wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh
# follow through installation prompts
rm Miniconda3-latest-Linux-x86_64.sh

Install Mamba on the base Conda environment:

conda install -n base -c conda-forge mamba --yes
conda activate base

Create a custom Conda environment named nextstrain:

# Create and activate a "nextstrain" environment
mamba create -n nextstrain
conda activate nextstrain

# Configure software channels; order is important!
conda config --env --add channels defaults
conda config --env --add channels bioconda
conda config --env --add channels conda-forge
conda config --env --set channel_priority strict

Install all the necessary software:

mamba install --yes \
    augur auspice nextalign nextclade \
    snakemake git epiweeks pangolin pangolearn

Set up the runtime:
```
nextstrain setup --set-default ambient
```

For ambient runtime installs

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

The final output from the last command should look like this, where <runtime> is the runtime option (e.g. Docker, Conda, or ambient) chosen in the first step:

Setting default environment to <runtime>.

All good!  Set up of <runtime> complete.

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

Next, try Running a pathogen workflow.

Update an existing installation

Update the Docker runtime:

nextstrain update docker

If the output notes that an update of the Nextstrain CLI itself is available, run the suggested command (after optionally reviewing the release notes).

Update the Conda runtime:

nextstrain update conda

If the output notes that an update of the Nextstrain CLI itself is available, run the suggested command (after optionally reviewing the release notes).

Update the nextstrain custom Conda environment.

mamba update -n base conda mamba
conda activate nextstrain
mamba update --all
nextstrain check-setup ambient

If the output of the final command notes that an update of the Nextstrain CLI itself is available, run the suggested command (after optionally reviewing the release notes).

Troubleshoot a broken installation

Running nextstrain check-setup docker will also report potential issues. Make sure there are no errors or warnings reported.

The Docker runtime requires that the Docker service is running on your computer behind the scenes. If you see a message like:

Cannot connect to the Docker daemon at […]. Is the docker daemon running?

Then it is likely that the Docker service is not running. On macOS and Windows, try quitting Docker Desktop (if it’s open) and restarting it. On Linux, try running sudo systemctl restart docker.

Running nextstrain check-setup conda will report potential issues. Make sure there are no errors or warnings reported.

You can forcibly setup the Conda runtime again by running:

nextstrain setup --force conda

This should rarely be necessary, but may help if you find yourself with a broken runtime.

Running nextstrain check-setup ambient will report potential issues. Make sure there are no errors or warnings reported.

Ensure that you’ve activated your custom Conda environment with conda activate nextstrain.

If Conda fails to install or update Nextstrain using the commands in the other sections above, it’s possible that Conda itself is out-of-date or that Conda cannot figure out how to resolve the environment’s dependencies. 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.

If you the above isn’t sufficient and you need more help troubleshooting, please post to our discussion forum where members of the community and the Nextstrain team can help out.

Alternate installation methods

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.

Uninstall

We do not have an automated uninstall process currently. Instead, follow these manual steps:

If the directory ~/.nextstrain exists, remove it.
If using the Docker runtime, remove all nextstrain/… Docker images:
docker image rm $(docker image ls -q "nextstrain/*")
Optionally, uninstall Docker if only used for Nextstrain.
If using the ambient runtime, remove the nextstrain custom Conda environment:
conda env remove -n nextstrain
Optionally, uninstall Conda if only used for Nextstrain.
On Windows, optionally, uninstall WSL if only used for Nextstrain.

Next steps

With Nextstrain installed, try Running a pathogen workflow next.