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.

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.

    Warning

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

    Install Docker Desktop for macOS.

  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.