Skip to content

3.26.0

Choose a tag to compare

View all tags
@nextstrain-bot nextstrain-bot released this 27 Oct 14:01
3.26.0
f35e2e8

Installation and usage

📚 Docsdocs.nextstrain.org/projects/nextclade
🌍 Webclades.nextstrain.org
📥 CLI
Linux x86_64glibc
musl*
Linux ARM64glibc
musl*
macOS***Apple Silicon
Intel
Windows x86_64.exe
🐋 Dockerdocker pull nextstrain/nextclade:3.26.0 (tags)
🐍 Condaconda install -c bioconda nextclade=3.26.0 (versions)**
⌨️ Source codegithub.com/nextstrain/nextclade
💾 Datasetsgithub.com/nextstrain/nextclade_data
🚩 IssuesReport bugs, suggest features

* glibc builds are faster and recommended, but require glibc >= 2.14. musl builds are static, run on older Linux distributions, and are slightly slower
** Bioconda releases need manual approval and can be delayed
*** macOS executables are not signed. See the install guide if macOS refuses to run them

Nextclade Web: tree page

The tree page embeds Auspice 3.1.0 (2026-10-15), up from 2.67.0 (2025-11-03), and gains many of Auspice's controls. See the tree page documentation for details.

  • Auspice 3.1.0: tip labels stay inside the tree, also when you zoom into a clade, and the tree controls work with the keyboard. SVG figures contain the tip labels and the diversity chart, write the legend and the caption as text that vector editors such as Inkscape and Illustrator can edit, and embed the Lato font, so that they look the same on every computer. Long legends use one column where they fit and scroll when they overflow. See the Auspice changelog for the versions from 2.68.0 to 3.1.0, and #1795, #1830
  • Panel layout as in Auspice: the tree, the map and the diversity chart have Auspice's sizes, so the top of the next panel shows below the tree. While the map is shown, the "Display" control in the sidebar places the tree and the map side by side ("grid") or one below the other ("full"). The sidebar has Auspice's width. On windows of 780 pixels or narrower it starts closed, and opens over the panels and darkens them. See #1831
  • Map of added coordinates: metadata with latitude and longitude columns shows a map of the sequences, which the Map section of the sidebar turns off and on. The map draws the country outlines, borders and names of Natural Earth from files that Nextclade Web serves itself, so it sends no request to another server. Samples at different coordinates stay apart, and rows with empty coordinates are skipped. SVG figures that contain the map give Natural Earth as the source of the map. Browsers without WebGL cannot draw the map, and Nextclade Web shows a message about it when you add coordinates. See #1830, #1831
  • Second tree: in an analysis of several datasets with more than one tree, the "Second tree" select draws another tree next to the viewed one, with lines between tips of the same name, to compare where samples are placed. Tips link only when their names are the same, for example when you name the segment sequences of a sample alike. A coloring by genotype colors both trees when they have the same genome annotation. See #1830, #1831
  • Stream trees: the "Show streamtrees" toggle draws each labeled clade as a stream: the density of its visible sequences along the divergence axis, divided by the current coloring. With the default filter, the streams show how your sequences spread over the clades. See #1830
  • From the results to the tree: a tree button at the end of each sequence name in the results table opens the tree filtered to that sequence. Shift+click adds the sequence to the selected sequences. A setting controls whether the tree zooms to the selected sequences, and Alt+click inverts this setting for one click. A click on a nucleotide or amino acid mutation in the sequence view opens the tree colored by the genotype at that position. See #1830, #1832
  • More sidebar controls: "Explode Tree By" splits the tree into subtrees where an attribute changes along a branch, for example one subtree per clade, and "Entropy" shows or hides the diversity chart. Shift+click a value in the legend to change the colors of the current coloring. The sidebar is also available in Chinese. See #1795, #1797
  • Your metadata on the tree: "Add metadata" in the sidebar, or a drop of files on the tree, adds the columns of CSV or TSV files as colorings and filters. The first column holds the sequence names, as in the input FASTA file. Node-data JSON files of Augur also work. The data stays in your browser. To use an Excel sheet, save it as a CSV or TSV file. See #1797
  • Kept view: the tree keeps its coloring, filters, zoom and added metadata while you visit other pages, until the next analysis. See #1797
  • Downloads: a new "NWK" button downloads the tree with the analyzed sequences placed onto it, in Newick format. The "JSON" and "NWK" buttons download the same files as the export page. The text below SVG figures lists the Nextclade dataset, the Nextclade version and the publications to cite. On narrow screens, the downloads are in one "Download" menu. See #1797
  • During the analysis: while the tree is expected, the tree page shows the stage of the analysis. Before, it showed the message that the dataset has no reference tree. For a dataset without a reference tree, the page gives the name of the dataset, lists the available results and explains how to use a custom reference tree. After all sequences are analyzed, the navigation bar shows "Building tree", so that large runs no longer look stalled. Before, it showed "Analyzed N/N". See #1794
  • No time view for trees with dated reference nodes: some reference trees, such as the one of the West Nile virus dataset, have a date on every node. The time view of these trees left out the analyzed sequences, which have no dates. The tree page now shows them by divergence only, without the time view, the clock layout and the date controls. See #1830

Nextclade Web: analysis and exports

  • Internal errors fail one sequence: when the analysis engine runs out of browser memory or stops on an internal error, only the sequence that was analyzed at that time fails, with an error message that states the cause, for example "Nextclade Web ran out of browser memory while allocating 2.4 GiB". Nextclade Web replaces the broken worker and continues with the other sequences, and stops the analysis after the fourth internal error of a run, because repeated internal errors indicate a problem that is not specific to one sequence. An internal error during an export fails only that export. Before, Nextclade Web stopped the whole analysis with an unclear message such as RuntimeError: unreachable, and later calls could run on the broken engine. See the errors and warnings documentation, #1805, #1806
  • Large alignment bands: sequences that need a large nucleotide alignment band, for example some mpox sequences, stopped the analysis with RuntimeError: unreachable, because the alignment matrix was copied once while it was created. Without the copy, the peak memory of an alignment drops from 9 to 5 bytes per band cell. When the memory for an alignment matrix still cannot be allocated, the sequence gets an error and the analysis continues. Results of Nextclade CLI do not change. See #1800
  • Free memory after very large alignments: the memory of an analysis worker grows to fit its largest alignment, and the browser cannot take it back while the worker runs. After some mpox sequences, a worker kept several GiB until the end of the run, and the browser tab could crash. Nextclade Web now replaces a worker whose memory grew above 1 GiB after its current sequence. Results do not change. See #1808
  • Failed sequences in exports: the CSV, TSV, JSON and NDJSON results of a dataset, also in the archive, now contain the sequences whose analysis failed, with their error message, as the Nextclade CLI outputs do. In a run with several datasets, a failed sequence is in the files of the dataset that Nextclade selected for it. Sequences without a dataset stay in the export of unclassified sequences. See #1803

Nextclade Web: layout and security

  • Phones, tablets and laptops: the pages of Nextclade Web fit small screens. See #1796
    • The navigation bar stays in one row and does not cover the page. Its breadcrumbs scroll sideways when they do not fit, and the analysis status keeps its room on laptop screens
    • Below 1200 pixels, the navigation menu contains the forum, Docker and GitHub links, which were not reachable before
    • The start page scrolls, so that the Run button and the dataset card stay reachable
    • Below 992 pixels, the dataset page shows the selected dataset and the Run button below the dataset list
    • Tabs, dataset search, dates and version badges, wide tables in dataset descriptions, the export page, the about page and the footer fit phone screens
    • On narrow screens, the row with the tree filters and the download buttons moves above the tree
    • Screen readers no longer announce the citation button as disabled
  • DOMPurify: the copy of DOMPurify that Auspice includes to remove unsafe HTML from dataset descriptions is updated from version 2.5.8 to 3.4.16, which fixes known sanitizer bypasses (GHSA-36jr-mh4h-2g58, GHSA-w5hq-g745-h8pq). See #1795

Analysis: Nextclade CLI and Nextclade Web

  • alignmentPreset in pathogen.json takes effect: Nextclade used the default preset unless the --alignment-preset CLI argument was given, although the documentation describes the field and some datasets set it. Both Nextclade CLI and Nextclade Web now apply the preset of the dataset. --alignment-preset replaces it, and alignment parameters set in pathogen.json or as CLI arguments still override the values of the preset. Results change for community/itps/orov/L/refseq, community/itps/zikav, community/masphl-bioinformatics/hav/vp1-2b-junction and community/masphl-bioinformatics/hav/whole-genome. See the sequence alignment documentation, #1810
  • Seed chains that link distant parts of the reference: some sequences match two distant parts of the reference, for example an mpox sequence from the inverted terminal repeats, which matches both ends of the genome. Nextclade aligned such a sequence with one deletion of almost the whole genome and good quality, and needed several GiB of memory, which crashed Nextclade Web. Such a sequence now gets an error before the alignment. The error message gives both parts of the reference and the implied deletion. Results of other sequences do not change. Two parameters control the check, and the short-sequences preset turns it off. See #1801
    • --max-seed-chain-deletion-ratio (maxSeedChainDeletionRatio in alignmentParams, default 10): the largest deletion between two successive seeds, as a multiple of the query length
    • --min-seed-chain-part-cover (minSeedChainPartCover in alignmentParams, default 0.2): the smallest fraction of the seed length that each part of the chain must hold for the sequence to be rejected
  • Warning when the alignment band may limit the alignment: Nextclade warns when the nucleotide alignment touches the boundary of the band and no wider band can be tried, because the wider band exceeds the band area limit or does not fit into memory, or because all retries are used while the score still rises. Before, Nextclade kept such an alignment without a message. The warning is in the warnings column of TSV and CSV outputs, the warnings array of JSON and NDJSON outputs, the tooltip of the sequence name in Nextclade Web, and the console output of Nextclade CLI. See the errors and warnings documentation, #1800
  • Message when the alignment band exceeds the limit: the message described a query much shorter than the reference as similar in length. It now describes short queries separately, with causes such as seed matches in distant repeated regions of the reference, and gives both ways to raise the limit: --max-band-area and alignmentParams.maxBandArea in pathogen.json. See #1800
  • Reverse-complement warning: the warning for a reverse-complemented sequence was missing for datasets without a genome annotation. Nextclade now reports it for all datasets. See #1800
  • Invalid regular expressions in aaMotifs: Nextclade compiles the regular expressions of aaMotifs in pathogen.json once, when the dataset loads. An invalid one, for example N[^P with an unclosed character class, gives an error message that contains the aaMotifs entry and the expression. Before, Nextclade CLI crashed with a backtrace and Nextclade Web aborted while it loaded the dataset. Results for valid datasets do not change. See #1802
  • Sequence names in the Newick tree: names with whitespace, brackets, quotes, colons, semicolons or commas, such as OV950637 (XL) in the SARS-CoV-2 reference tree, are now written in single quotes, for example 'OV950637 (XL)', with each single quote in the name doubled, as the Newick format requires. Tree tools read such unquoted names as Newick syntax or rejected the file. Other names do not change. See the tree output documentation, #1798

Nextclade CLI: errors and outputs

  • Write errors of output files: nextclade run, nextclade sort and the other commands no longer crash when an output file cannot be written, for example on a full disk. They end with exit code 1 and an error message with the file path, or standard output, and the cause that the operating system reports. This includes CSV, TSV, TBL and GFF3 outputs, whose errors lost their cause or, for GFF3, went unnoticed. When one output fails at the end of nextclade run or nextclade sort, the other outputs, including the tree outputs, are still completed, and the errors of all outputs are reported. A command that stops early, for example after an error in an input file, warns about each incomplete or missing output. See #1821
  • Closed output pipe: commands that print data, such as nextclade dataset list | head, crashed when the reader stopped early. They now end quietly with exit code 0, as standard Unix tools do. Outputs written to standard output with -, for example nextclade run --output-fasta - sequences.fasta | head, no longer end with an error. Nextclade then stops writing to standard output and still writes all other outputs, for example --output-tsv results.tsv. nextclade sort does the same for --output-results-tsv - and the table of --verbose. See #1821
  • Results JSON on standard output: nextclade run --output-json - printed the results JSON twice, and now prints it once. An error while writing the results JSON crashed the command, and now ends it with an error message. See #1821
  • Read errors of input files: when an input file cannot be read, for example a truncated or damaged sequences.fasta.gz, the error message contains the file path once, with the compression format and the cause. Before, it said "Filename: None". See #1825
  • Read errors of --input-pathogen-json: with --input-ref, nextclade run ignored a --input-pathogen-json file that it could not read, for example a missing or damaged file, and used the default pathogen settings without a message, so the QC and analysis settings could differ from the file. Nextclade now ends with an error message that contains the file path. See #1826
  • Parse errors of pathogen.json and the minimizer index: when pathogen.json of a dataset or of --input-pathogen-json, or the minimizer index of nextclade sort, cannot be parsed, the error message contains the file path, as the errors of the other dataset files do. See #1828
  • --jobs 0 is an error: --jobs now requires 1 or more. With 0, nextclade run failed with the unclear error "When sending a FastaRecord" and left empty output files, and nextclade sort crashed. See #1820

Nextclade CLI: nextclade sort

  • Errors: nextclade sort no longer crashes when it cannot read an input file or create an output file, and ends with an error message and exit code 1. See #1821
  • --global with sequences from standard input: --global reads the sequences twice, once to find the best datasets and once to write the outputs. With sequences from standard input, the second read found nothing and the outputs were empty. Nextclade now copies standard input into a temporary file and reads that file both times. See #1824
  • Summary of --global --verbose: the "Suggested datasets" summary now follows the per-sequence table, as without --global. See #1823
  • Dataset counts of --verbose: the "Suggested datasets" summary counted the first sequence of each dataset twice, so "Num. seq", the total and "Percent" were wrong, and the percentages were too low for datasets with many sequences. With --all-matches, the total counted each pair of a sequence and a matching dataset. The summary now counts each sequence once for each of its datasets and once in the total. With --all-matches, the percentages can add up to more than 100%. See #1822

Nextclade CLI: network and security

  • Network options for nextclade run: nextclade run now takes the network options of nextclade dataset get and uses them when it downloads a dataset with --dataset-name: --proxy, --proxy-user, --proxy-pass, --extra-ca-certs, and the new --proxy-pass-file and --http-timeout. Each option can also be set with an environment variable, and a command-line argument takes precedence over its variable. See #1815
    • Variables: NEXTCLADE_PROXY, NEXTCLADE_PROXY_USER, NEXTCLADE_PROXY_PASS, NEXTCLADE_PROXY_PASS_FILE, NEXTCLADE_EXTRA_CA_CERTS, NEXTCLADE_HTTP_TIMEOUT
    • A variable set to an empty value, for example NEXTCLADE_PROXY= from ${VAR:-} in a container configuration, counts as not set
    • Nextclade checks the values only when it downloads, so an invalid value does not stop a command that downloads nothing. An invalid value, including one that is not valid UTF-8 text, gives an error message that contains both the option and the variable
    • Other users of the machine can see command-line arguments, so Nextclade warns when --proxy-pass gives a password. Use NEXTCLADE_PROXY_PASS or --proxy-pass-file <PATH> (one trailing newline is removed) instead. When one password option is an argument and the other a variable, the argument takes precedence. Two arguments, or two variables, are an error when Nextclade downloads. --help does not print the values of the proxy variables
  • Proxy settings and download timeout: see #1815
    • With --proxy, hosts in NO_PROXY (or no_proxy) are reached directly
    • --proxy and NEXTCLADE_PROXY accept a proxy without a scheme, for example 10.0.0.1:3128, as an HTTP proxy
    • --proxy-user, --proxy-pass and --proxy-pass-file apply only to a proxy given with --proxy or NEXTCLADE_PROXY. For a proxy from HTTPS_PROXY, HTTP_PROXY or ALL_PROXY, Nextclade warns, and the credentials belong in the URL of that variable, for example http://user:password@proxy.example.com:3128. Nextclade checks these options for every download, so for example a user without a password is always an error
    • Without --proxy, Nextclade uses HTTPS_PROXY, HTTP_PROXY and ALL_PROXY (upper or lower case) with NO_PROXY, and the system proxy settings on macOS and Windows when none of these is set. A variable set to an empty value counts as set, so HTTPS_PROXY= alone makes Nextclade connect directly. A value that is not valid UTF-8 text is an error when Nextclade uses the variable
    • Downloads are no longer cut off after 30 seconds. Each HTTP request may take up to 600 seconds, from connecting to the last byte. --http-timeout <SECONDS> or NEXTCLADE_HTTP_TIMEOUT changes the limit, and 0 disables it. The error message for a request over the limit contains the option
  • Server URL with a trailing slash: --server accepts a URL that ends with /, for example --server https://data.clades.nextstrain.org/v3/. Before, Nextclade requested https://data.clades.nextstrain.org/v3//index.json, which some servers do not serve. See #1819
  • Certificate decisions of the operating system: Nextclade added its built-in copy of Mozilla's list of certificate authorities (CAs) to the CAs of the operating system, so it kept trusting CAs that Apple or Microsoft no longer trust. If downloads now fail with a certificate error on an outdated system, update its CA certificates (for example the ca-certificates package on Linux), or add the missing CA with --extra-ca-certs. See #1816
    • macOS and Windows: the operating system alone decides which CAs to trust
    • Linux and other Unix systems except macOS: Nextclade trusts the system certificate store, and uses the built-in Mozilla list only when the system has no usable CA certificates, for example in the scratch Docker image. When SSL_CERT_FILE is set, or SSL_CERT_DIR is set to a directory, but they provide no usable CA certificates, Nextclade stops with an error. An SSL_CERT_DIR that is not a directory, such as an empty value, counts as not set
    • A file given with --extra-ca-certs that contains no certificates or an invalid one gives an error message that contains the file path
  • TLS and network libraries: rustls is updated to 0.23.46, which fixes RUSTSEC-2026-0285 and RUSTSEC-2026-0349. bytes, crossbeam-epoch and time are updated to versions that fix published advisories, and reqwest to a newer version. See #1812
  • Extraction of dataset archives: nextclade dataset get --output-dir protects against crafted archives from a compromised or impersonated dataset server. See #1813, #1829
    • It extracts only the regular files at the root of the archive and ignores all other entries, such as directories and paths that point outside of the output directory
    • It rejects archives with symbolic links, with file names that Windows does not allow (such as aux.txt or names with :), or with more than 10 000 entries, and stops when the unpacked archive exceeds 1 GiB
    • It deletes an existing file or symbolic link of the same name before it creates the extracted file, so symbolic links in the output directory no longer redirect the extracted files
    • The zip library is updated from 7.0.0 to 9.0.5, and rust_xlsxwriter from 0.92.2 to 0.101.0, which uses the same zip version. Older zip versions are affected by RUSTSEC-2026-0367, RUSTSEC-2026-0368 and RUSTSEC-2026-0369 in their extraction functions, which the old extraction used and the new one does not

Nextclade CLI: release files

  • Verifiable release downloads: release pages include a SHA256SUMS file with the SHA-256 checksums of all executables, and a GitHub build provenance attestation for each executable, to check that a download is complete and that the Nextclade release workflow on GitHub built it. See the installation documentation, #1814
  • Linux glibc executables in minimal container images: nextclade-x86_64-unknown-linux-gnu and nextclade-aarch64-unknown-linux-gnu needed libgcc_s.so.1, which minimal glibc images such as gcr.io/distroless/base do not have. The executables now contain the necessary code of this library. See #1799

Citation

If you use results obtained with Nextclade in a publication, please cite our paper:

Aksamentov, I., Roemer, C., Hodcroft, E. B., & Neher, R. A., (2021). Nextclade: clade assignment, mutation calling and quality control for viral genomes. Journal of Open Source Software, 6(67), 3773, https://doi.org/10.21105/joss.03773

(bibtex)

Where possible, provide a link to Nextclade Web: https://clades.nextstrain.org

Assets 10
Loading