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:
Nextstrain CLI, for access to other tools and management of workflows
Augur, for bioinformatic analysis of pathogen genomes
Auspice, for interactive visualization of pathogen evolution
When completed, youâll be ready to run Nextstrain workflows.
Table of Contents
Installation stepsď
Steps vary by runtime option (Docker, Conda, ambient) and host interface (macOS, Windows (WSL), Windows (PowerShell), Linux). For help choosing, refer to our Frequently Asked Questions (FAQ), such as:
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.
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 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)â.
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.
Set up a Nextstrain runtimeď
Install Docker on your computer.
Install Docker Desktop for Windows with the WSL 2 backend.
Note
Make sure to follow through to the Enabling Docker support in WSL 2 distros section and the last step of enabling WSL Integration. If you forget to do this,
dockerwonât work in the WSL terminal.For Windows (WSL) 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_homefolder 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.Install Windows Subsystem for Linux (WSL) 2. You may have to restart your machine when configuring WSL.
Note
Steps for other Linux distributions (Debian, CentOS, RHEL, etc.) will be similar, though specific commands may vary slightly.
Install Docker Engine using the standard Ubuntu package:
sudo apt install docker.io
or see Docker Engineâs installation documentation for alternative methods.
Add your user to the
dockergroup:sudo gpasswd --add $USER docker
Log out and back in again for the group change to take effect.
Set up the runtime:
nextstrain setup --set-default docker
Set up the runtime:
nextstrain setup --set-default conda
Set up the runtime:
nextstrain setup --set-default conda
Note
Due to installation constraints, there is no way to use Nextstrainâs Conda runtime on Windows directly. Starting from the beginning, follow steps for Windows (WSL) if the Conda runtime is desired, or use the Docker runtime instead.
Set up the runtime:
nextstrain setup --set-default conda
The ambient runtime does not require a particular setup method; it will work as long as the programs you wish to use are available.
The following describes how to accomplish this using a custom Conda environment as an example. You should be familiar with the basics of Conda before proceeding.
Warning
If step 2 fails, you might have an Apple silicon version of Conda installed. See this FAQ section for workarounds.
Activate a Conda environment that you wish to use:
conda activate <your-environment-name>
Install all the necessary software:
Note
We recommend Mamba as a drop-in replacement for
condato have faster installation times.conda install --override-channels --strict-channel-priority \ -c conda-forge -c bioconda --yes \ augur auspice nextalign nextclade \ snakemake git epiweeks pangolin pangolearn
Set the runtime:
nextstrain setup --set-default ambient
Activate a Conda environment that you wish to use:
conda activate <your-environment-name>
Install all the necessary software:
Note
We recommend Mamba as a drop-in replacement for
condato have faster installation times.conda install --override-channels --strict-channel-priority \ -c conda-forge -c bioconda --yes \ augur auspice nextalign nextclade \ snakemake git epiweeks pangolin pangolearn
Set the runtime:
nextstrain setup --set-default ambient
Note
Due to installation constraints, there is no way to use the ambient runtime on Windows directly. Starting from the beginning, follow steps for Windows (WSL) if the ambient runtime is desired, or use the Docker runtime instead.
Activate a Conda environment that you wish to use:
conda activate <your-environment-name>
Install all the necessary software:
Note
We recommend Mamba as a drop-in replacement for
condato have faster installation times.conda install --override-channels --strict-channel-priority \ -c conda-forge -c bioconda --yes \ augur auspice nextalign nextclade \ snakemake git epiweeks pangolin pangolearn
Set the runtime:
nextstrain setup --set-default ambient
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.
Try running Augur and Auspiceď
Enter an interactive Nextstrain shell in the current directory (
.).nextstrain shell .
Run Augur.
augur --helpRun Auspice.
auspice --helpExit the Nextstrain shell.
exit
Enter an interactive Nextstrain shell in the current directory (
.).nextstrain shell .
Run Augur.
augur --helpRun Auspice.
auspice --helpExit the Nextstrain shell.
exit
Note
This will vary depending on how your ambient runtime is set up.
If using a custom Conda environment, activate it.
conda activate <your-environment-name>
Run Augur.
augur --helpRun Auspice.
auspice --helpDeactivate the custom Conda environment.
conda deactivate
Next stepsď
With Nextstrain installed, try Running a pathogen workflow next.
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.
Managing an existing installationď
See Managing a Nextstrain Installation for steps to update, troubleshoot, or uninstall Nextstrain tools.