Installation
Hint
This is a reference page with brief pointers for installing and setting up Nextstrain CLI. For a more comprehensive installation guide, please see our general Nextstrain installation page.
The nextstrain
command
Install the nextstrain
command with one of the installation methods below.
Standalone
Use our installers to quickly install a self-contained (“standalone”) version of Nextstrain CLI on Linux:
curl -fsSL --proto '=https' https://nextstrain.org/cli/installer/linux | bash
macOS:
curl -fsSL --proto '=https' https://nextstrain.org/cli/installer/mac | bash
or Windows:
Invoke-RestMethod https://nextstrain.org/cli/installer/windows | Invoke-Expression
Follow the instructions from the installer at the end.
From PyPI
Note
Nextstrain CLI is written in Python 3 and requires at least Python 3.6. There
are many ways to install Python 3 on Windows, macOS, or Linux, including the
official packages, Homebrew for macOS, and the Anaconda Distribution.
Details are beyond the scope of this guide, but make sure you install Python
3.6 or higher. You may already have Python 3 installed, especially if you’re on
Linux. Check by running python --version
or python3 --version
.
Use Pip to install the nextstrain-cli package on PyPI:
$ python3 -m pip install nextstrain-cli
Collecting nextstrain-cli
[…a lot of output…]
Successfully installed nextstrain-cli-6.0.2
This package also works great with Pipx, a nice alternative to Pip for command-line apps like this one:
$ pipx install nextstrain-cli
Installing to directory '/home/tom/.local/pipx/venvs/nextstrain-cli'
installed package nextstrain-cli 6.0.2, Python 3.6.9
These apps are now globally available
- nextstrain
done! ✨ 🌟 ✨
From Bioconda
Use Conda (or Mamba) to install the nextstrain-cli package in Bioconda:
conda install nextstrain-cli \
-c conda-forge -c bioconda \
--strict-channel-priority \
--override-channels
Checking the version
Whatever installation method you choose, make sure the nextstrain
command
is available after installation by running nextstrain version
:
$ nextstrain version
nextstrain.cli 6.0.2
The version you get will probably be different than the one shown in the example above.
Runtimes
The Nextstrain CLI provides a consistent interface and computing environment for running and visualizing Nextstrain pathogen builds across several different computing platforms, such as Docker, Conda, Singularity, and AWS Batch.
We call the provided computing environments the Nextstrain runtimes. Each runtime provides specific versions of Nextstrain’s software components, like Augur and Auspice.
At least one of these runtimes must be setup in order for many of
nextstrain
’s subcommands to work, such as nextstrain build
and
nextstrain view
.
The default runtime is Docker, using the nextstrain/base container image. Containers provide a tremendous amount of benefit for scientific workflows by isolating dependencies and increasing reproducibility. However, they’re not always appropriate, so a Conda runtime, Singularity runtime, and “ambient” runtime are also supported. The installation and setup of supported runtimes is described below.
Docker
Docker is a very popular container system freely-available for all platforms. When you use Docker with the Nextstrain CLI, you don’t need to install any other Nextstrain software dependencies as validated versions are already bundled into a container image by the Nextstrain team.
On macOS, download and install Docker Desktop, also known previously as “Docker for Mac”.
On Linux, install Docker with the standard package manager. For example, on
Ubuntu, you can install Docker with sudo apt install docker.io
.
On Windows, install Docker Desktop with its support for a WSL2 backend.
Once you’ve installed Docker, proceed with checking your setup.
Conda
Conda is a very popular packaging system freely-available for all platforms. When you use Nextstrain CLI’s built-in Conda support, you don’t need to install any other Nextstrain software dependencies yourself as they’re automatically managed in an isolated location (isolated even from other Conda environments you may manage yourself).
On macOS and Linux, run nextstrain setup conda
to get started.
This runtime is not directly supported on Windows, but you can use WSL2 to “switch” to Linux and run the above setup command.
Singularity
Singularity is a container system freely-available for Linux platforms. It is commonly available on institutional HPC systems as an alternative to Docker, which is often not supported on such systems. When you use Singularity with the Nextstrain CLI, you don’t need to install any other Nextstrain software dependencies as validated versions are already bundled into a container image by the Nextstrain team.
Run nextstrain setup singularity
to get started.
Note that the Singularity project forked into two separate projects in late
2021: SingularityCE under Sylabs and Apptainer under the Linux
Foundation. Either fork should work with Nextstrain CLI, as both projects
still provide very similar interfaces and functionality via the singularity
command. You can read Sylab’s announcement and Apptainer’s announcement
for more information on the fork.
Ambient
The “ambient” runtime allows you to use the Nextstrain CLI with your own ambient setup, for when you cannot or do not want to have Nextstrain CLI manage its own runtime.
However, you will need to make sure all of the Nextstrain software dependencies are available locally or “ambiently” on your computer. A common way to do this is by manually using Conda to manage your own environment that includes the required software, however you’re responsible for making sure the correct software is installed and kept up-to-date. It is also possible to install the required Nextstrain software Augur and Auspice and their dependencies manually, although this is not recommended.
Once you’ve installed dependencies, proceed with checking your setup.
AWS Batch
AWS Batch is an advanced computing platform which allows you to launch and monitor Nextstrain builds in the cloud from the comfort of your own computer. The same image used by the local Docker runtime is used by AWS Batch, making your builds more reproducible, and builds have access to computers with very large CPU and memory allocations if necessary.
The initial setup is quite a bit more involved, but detailed instructions are available.
Once you’ve setup AWS, proceed with checking your setup.
Checking your setup
After installation and setup, run nextstrain check-setup --set-default
to
ensure everything works and automatically pick an appropriate default runtime
based on what’s available. You should see output similar to the following:
$ nextstrain check-setup --set-default
nextstrain-cli is up to date!
Testing your setup…
# docker is supported
✔ yes: docker is installed
✔ yes: docker run works
✔ yes: containers have access to >2 GiB of memory
✔ yes: image is new enough for this CLI version
# conda is supported
✔ yes: operating system is supported
✔ yes: runtime data dir doesn't have spaces
✔ yes: snakemake is installed and runnable
✔ yes: augur is installed and runnable
✔ yes: auspice is installed and runnable
# singularity is supported
✔ yes: singularity is installed
✔ yes: singularity works
# ambient is not supported
✔ yes: snakemake is installed and runnable
✘ no: augur is installed and runnable
✘ no: auspice is installed and runnable
# aws-batch is not supported
✘ no: job description "nextstrain-job" exists
✘ no: job queue "nextstrain-job-queue" exists
✘ no: S3 bucket "nextstrain-jobs" exists
All good! Supported Nextstrain runtimes: docker, conda, singularity
Setting default runtime to docker.
If the output doesn’t say “All good!” and list at least one supported Nextstrain runtime (typically Docker, Conda, Singularity, or ambient), then something may be wrong with your installation.
The default is written to the ~/.nextstrain/config
file. If multiple
runtimes are supported, you can override the default for specific runs
using command-line options such as --docker
, --conda
,
--singularity
, --ambient
, and --aws-batch
, e.g. nextstrain build
--ambient …
.