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:
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.
Install Docker on your computer.
Install Windows Subsystem for Linux (WSL) 2. You may have to restart your machine when configuring WSL.
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,
docker
wonât work in the WSL terminal.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.) 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
docker
group: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
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 WSL on Windows if the Conda runtime is desired, or use the Docker runtime instead.
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:
-
Note
This is the Intel x86 64-bit installer, which we recommend even for Mac computers with Apple silicon (e.g. M1).
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
Note
Due to installation constraints, there is no way to use the ambient runtime on Windows directly. Starting from the beginning, follow steps for WSL on Windows if the ambient runtime is desired, or use the Docker runtime instead.
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 nextstrainOptionally, 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.