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.

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

Then, install a Nextstrain runtime.

  1. Install Docker on your computer.

  2. Set up the runtime:

    nextstrain setup --set-default docker
    

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).

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.

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:

  1. If the directory ~/.nextstrain exists, remove it.

  2. 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.

  3. If using the ambient runtime, remove the nextstrain custom Conda environment:

    conda env remove -n nextstrain
    

    Optionally, uninstall Conda if only used for Nextstrain.

  4. On Windows, optionally, uninstall WSL if only used for Nextstrain.

Next steps

With Nextstrain installed, try Running a pathogen workflow next.