10.4.1

These release notes are automatically extracted from the full changelog.

Bug fixes

• The dependency on types-boto3-s3 is now development-only (the dev extra). This eases Conda packaging and is consistent with dev-only dependencies on other type definition packages. (#485)

10.4.0

These release notes are automatically extracted from the full changelog.

Improvements

• nextstrain run now resolves workflow names by looking in the pathogen registration (nextstrain-pathogen.yaml) for an explicitly registered path. If no path is registered for a workflow, nextstrain run still falls back to using the workflow name for the workflow path.

  This allows for workflow names that are not also directory paths within the pathogen source, which is useful for pathogens that are structured non-conventionally for one reason or another. The decoupling of workflow names from paths also means that the workflow can be relocated within the pathogen repo without breaking the name (i.e. the external interface to the workflow).

  As an example, the following workflow registration:

  workflows:
    phylogenetic:
      path: .
      compatibility:
        nextstrain run: yes

  would allow invocation of a phylogenetic workflow located at the top-level of the pathogen source, such as in zika-tutorial. (#481)

• Pathogen registration files (nextstrain-pathogen.yaml) now have a formal schema, https://nextstrain.org/schemas/pathogen/v0, and registrations will be validated against the schema if they declare so with $schema.

  Unknown $schema ids are ignored. Validation errors will cause the pathogen registration file to be ignored (as if it didn't exist).

  Malformed registration files are warned about during the initial pathogen setup with nextstrain setup and during subsequent pathogen version updates with nextstrain update, but not when using an existing pathogen setup with nextstrain run (so as not to be too noisy). (#482)

• The AWS Batch runtime now supports storing workdir and envdir archives in S3 under a key prefix. This optional key prefix is provided after the bucket name in the --aws-batch-s3-bucket option or the equivalent aws-batch.s3-bucket config field or NEXTSTRAIN_AWS_BATCH_S3_BUCKET environment variable. For example, providing

  --aws-batch-s3-bucket=some-bucket/a/prefix/
  

  would result in workdir archives stored at

  s3://some-bucket/a/prefix/6116f3e3-9bc0-4769-99e3-adb71b4d82c0.zip
  

  For extra clarity, particularly when providing a prefix, the value may now be specified as a URL (e.g. s3://some-bucket/a/prefix or s3://another-bucket), though, for backwards compatibility, doing so is not required. A key prefix may be useful for the organization of the objects in a bucket, particularly when the bucket is accessed directly, outside of Nextstrain CLI. (#483)

Bug fixes

• The AWS configuration for S3 operations for the AWS Batch runtime no longer sets 3 as the max number of attempts for retries. To explicitly control retries yourself, use AWS' own support via config files (max_attempts) and environment variables (AWS_MAX_ATTEMPTS). The previous configuration precluded the use these AWS config files and env vars to control max attempts. Note that 3 attempts is already the AWS default, so no behaviour change is expected and no action is needed during upgrade. (#483)

10.3.0

These release notes are automatically extracted from the full changelog.

This release adds explicit (i.e. tested) support for Python version 3.13. (#473)

Note that this Python version support only matters if you're installing Nextstrain CLI from PyPI or Bioconda (c.f.). It does not apply if you're installing Nextstrain CLI using the standalone installation method we recommend in the Nextstrain installation documentation. In that case, a supported Python version is always bundled with nextstrain.

Improvements

• nextstrain setup <pathogen> and nextstrain version --pathogens now list the available workflows (e.g. ingest, phylogenetic) for a pathogen if the workflows are registered as compatible with nextstrain run in the pathogen's nextstrain-pathogen.yaml file. (#461, #472)

• Snakemake's storage support downloaded files (stored in .snakemake/storage/) are now downloaded from AWS Batch builds by default.

  The runtime image used must be at least nextstrain/base:build-20250721T201347Z for these Snakemake storage files to be available for download from the AWS Batch job. (#460)

• nextstrain run now supports an alternative invocation where a path to a local directory that is a pathogen repository can be given instead of a pathogen name (and optionally version). This allows nextstrain run to be used with pathogen repos managed outside of Nextstrain CLI (i.e. not by nextstrain setup and nextstrain update), which can be useful for the analysis directory support and local testing. The workflow to run is still given separately by name (not path). (#476)

• When nextstrain setup <pathogen> and nextstrain update <pathogen> encounter an authentication error downloading from pathogen source URLs, the error message now includes a hint, if applicable, noting the presence of netrc-provided credentials and possible resolutions. This aids in resolving errors arising from stale GitHub credentials present in some users' netrc files (as managed by older versions of the GitHub CLI, gh). (#479)

• When Nextstrain CLI detects that a new version of itself is available, it will now output the instructions on how to upgrade to that new version after (instead of before) the normal output from the running command. This makes it easier to find and follow the instructions when output is long. The notices of the new version will be output both before and after normal output. (#475)

• For most installation methods (i.e. standalone, Pip, pipx, and Conda), the process of updating Nextstrain CLI itself is now automated by a single nextstrain update cli command. This is suggested in new version notices emitted by automatic new version checks (along with the previously-suggested update commands that vary by installation method). Integrating with nextstrain update puts updates to the CLI alongside updates to the runtimes and pathogens. (#475)

Bug fixes

• nextstrain setup <pathogen>@<version> and nextstrain update <pathogen>@<version> no longer result in a 404 error if <version> includes a slash and it is a valid version specifier. (#459)

• Reverting changes made in 10.2.1, nextstrain setup <pathogen> and nextstrain update <pathogen> will once again attempt to use a local netrc file for authentication when downloading pathogen source URLs. This also reinstates support in those cases for configuring outgoing network proxies and CA certificate trust stores via environment variables. Support for private repositories is not unintentional and is something we intend to provide. (#478)

• nextstrain run now overrides (i.e. suppresses) any "workdir:" directives in a workflow by explicitly setting the working directory when it invokes Snakemake. This avoids writing files into the pathogen/workflow source directories when non-compatible (or broken) workflows are used with nextstrain run despite the warnings issued. Such workflows are more likely to error and fail now early on rather than "succeed" but produce output files in the wrong location. (#476)

• When a standalone installation of Nextstrain CLI suggests a command to run to update itself, that command now takes into account non-default installation paths so that the new version is installed to the same place as the current version. (#474)

10.2.1.post1

These release notes are automatically extracted from the full changelog.

See also changes in 10.2.1 which was an unreleased version.

Development

• The release script now keeps changelogs in sync. (#446)

10.2.0

These release notes are automatically extracted from the full changelog.

Development

• nextstrain setup conda and nextstrain update conda now respect an optional NEXTSTRAIN_CONDA_OVERRIDE_SUBDIR environment variable that when set overrides the default behaviour of detecting the best Conda subdir that's usable for the platform.

  This may be used, for example, to force the use of the x86_64 architecture (osx-64 subdir) on macOS hardware that's natively the aarch64 (aka arm64, Apple Silicon, M1/M2/...) architecture (osx-arm64 subdir):

  NEXTSTRAIN_CONDA_OVERRIDE_SUBDIR=osx-64 nextstrain setup conda
  

  The variable must be set for every invocation of nextstrain setup conda or nextstrain update conda, otherwise the default behaviour will apply and the subdir in use by the runtime may be automatically switched. (#437)

10.1.0

These release notes are automatically extracted from the full changelog.

Improvements

• Use of an alternate Conda package repository is now supported during nextstrain setup conda and nextstrain update conda if you cannot or do not want to use the default package repository hosted by Anaconda. Set the NEXTSTRAIN_CONDA_CHANNEL_ALIAS environment variable to the base URL of the repository. This corresponds to the channel_alias Conda config setting. (#436)

• The Conda runtime no longer requires Rosetta 2 for macOS running on aarch64 (aka arm64, Apple Silicon, M1/M2/...) hardware. This improves performance when using the runtime. Run nextstrain update conda to receive the update. (#436)

Development

• The NEXTSTRAIN_CONDA_MICROMAMBA_VERSION environment variable is no longer supported (i.e. for use with nextstrain setup conda). Please use NEXTSTRAIN_CONDA_MICROMAMBA_URL instead. (#436)

10.0.0

These release notes are automatically extracted from the full changelog.

This release is the first to include initial support for setting up and running pathogen workflows without the co-mingling of our workflow source code with your inputs and outputs (e.g. your config.yaml, data/, and results/) and without needing to download source code or use Git yourself. Pathogens are first set up with nextstrain setup and their workflows may then be run using nextstrain run, a new command in this release. These features are part of our broader "workflows as programs" endeavor.

Features

• A new command, nextstrain run, for running pathogen workflows in a more managed way as part of our broader "workflows as programs" endeavor.

  Workflows (e.g. ingest, phylogenetic) for a pathogen are run in a Nextstrain runtime with config and input (e.g. config.yaml, data/) from an analysis directory you provide and outputs (e.g. results/) written to that same directory.

  Pathogens (e.g. measles) are initially set up using nextstrain setup and can be updated over time as desired using nextstrain update. Multiple versions of a pathogen may be set up and run independently without conflict, allowing for comparisons of output across versions. The same pathogen workflow may also be concurrently run multiple times with separate analysis directories (i.e. different configs, input data, etc.) without conflict, allowing for independent outputs and analyses. Set up pathogens and their versions are listed by nextstrain version --pathogens.

  Compared to nextstrain build, this new nextstrain run command is a higher-level interface to running pathogen workflows that does not require knowledge of Git or management of pathogen repositories and source code. For now, the nextstrain build command remains more suitable for active authorship and development of workflows. (#407)

Improvements

• The results of setup checks performed by nextstrain setup and nextstrain check-setup are now shown individually as they complete instead of waiting for all checks to complete before showing results. This makes it more clear that work is being done when checks take a second or two. (#418)

• Commands which make web requests on your behalf (e.g. nextstrain remote, nextstrain login, nextstrain setup, nextstrain update) now include an appropriate and informative User-Agent header, e.g.

  Nextstrain-CLI/10.0.0 (https://nextstrain.org/cli) Python/3.10.9 python-requests/2.32.3 platform/Linux-x86_64 installer/standalone tty/yes
  

  instead of the previous generic User-Agent, e.g.

  python-requests/2.32.3
  

  The new User-Agent includes the Nextstrain CLI version as well as basic information on several important software components. This information is non-identifying and useful for our troubleshooting and aggregation of usage metrics. You may opt to omit it, however, by setting the NEXTSTRAIN_CLI_USER_AGENT_MINIMAL environment variable to 1 (or another truthy value). In that case, the User-Agent only includes the CLI version, e.g.:

  Nextstrain-CLI/10.0.0 (https://nextstrain.org/cli)
  

  We recommend leaving the default User-Agent enabled unless the minimal variant is necessary for your circumstances. (#432)

• When checking for upgrades for Nextstrain CLI itself during nextstrain check-setup and nextstrain update, the latest version is now fetched from nextstrain.org instead of pypi.org. This gives us insights into usage and also more flexibility to shift how we're releasing and distributing this project. (#434)

9.0.0

These release notes are automatically extracted from the full changelog.

This release contains a potentially-breaking change for any usages of the --sacra option, though we expect no one is using it. The change is described below.

Improvements

• nextstrain version now reports itself as "Nextstrain CLI" (instead of "nextstrain.cli") and indicates if it is a "standalone" installation (self-contained, bundles Python) or not. (#419)

• Colorized and bolded output is disabled when stdout is not attached to a terminal (e.g. is redirected to a file, piped to another program, etc.) or when the NO_COLOR environment variable is set to a non-empty value. (#419)

• The readability of --help output is improved by the addition of blank lines between argument/option descriptions. (#419)

• AWS Batch builds now support development overlays such as --augur and --auspice. To use this functionality, you'll need at least nextstrain/base:build-20250321T184358Z or newer of the Nextstrain Docker runtime image. Compatibility of the runtime image is checked automatically when overlays are used with AWS Batch. (#419, #423)

• The --sacra option, intended for use during development, is no longer supported by nextstrain build, nextstrain view, or nextstrain shell. Sacra, long-defunct and never used, was removed from the Nextstrain runtime image itself over 4 years ago (first absent in nextstrain/base:build-20201213T084302Z, last present in nextstrain/base:build-20201212T165623Z). This is technically a potentially-breaking change, although almost certainly affects no one. (#419)

Bug fixes

• Fixed a rare but possible error case in nextstrain view and nextstrain login when running under a copy of Python with IPv6 disabled on a system with IPv6 enabled. In such situations, IPv6 addresses will now be ignored. (#415)

• An authentication callback URL containing an unresolvable hostname is no longer considered to have a loopback (local-only) address, i.e. is not considered safe/suitable for use. (#416)

• nextstrain view now correctly handles IPv6 host addresses in the URL opened in a browser (if any). (#417)

• nextstrain login now correctly handles OAuth 2.0 authorization endpoint URLs (which are obtained automatically from OpenID Connect 1.0 metadata discovery) with existing query parameters in them. This bug likely affected approximately no one; logging into nextstrain.org was unaffected and all known users of non-nextstrain.org remotes were also unaffected. (#419)

• File timestamps for results files downloaded from an AWS Batch build are now correctly restored even if the expected extraction path differs from the actual extraction path due to ZIP security precautions. This bug likely affected approximately no one. (#419)

Development

• Goodbye, Mypy! We now use only Pyright for type checking. Both type checkers used to contribute to our development in their own way, but over time Pyright's become more sophisticated and Mypy's required more workarounds to appease it than issues it caught. So long, and thanks for all the fish type checks! (#419)

• Cram test files are now supported, with one example file for now. (#419)

• NEXTSTRAIN_HOME is now set for tests so as to avoid interference with the local user's personal config and data. (#419)

• Running tests no longer opens a browser. \o/ (#419)

8.5.4

These release notes are automatically extracted from the full changelog.

Bug fixes

• It is no longer a fatal error if the logs for a completed AWS Batch job cannot be fetched for some reason. nextstrain build will warn about the error but continue on with printing the job status (e.g. success or reason for failure) and, if applicable, downloading job results. (#406)

8.5.3

These release notes are automatically extracted from the full changelog.

Bug fixes

• Authentication established via nextstrain login and used by the nextstrain remote family of commands no longer verifies the "issued at" (iat) time of the received tokens in order to avoid the following error:

  ImmatureSignatureError: The token is not yet valid (iat).
  

  This error was seen by users who's system time was slightly lagged, and it prevented them from logging in or renewing their authentication. (#394)