From 0ea6a039c5ec5ce084105365c5073133f6cffa2d Mon Sep 17 00:00:00 2001 From: Ben Sherman Date: Mon, 14 Sep 2026 19:35:52 -0500 Subject: [PATCH 1/7] Add 26.10 migration notes Signed-off-by: Ben Sherman --- docs/migrations/25-10.mdx | 4 + docs/migrations/26-04.mdx | 6 ++ docs/migrations/26-10.mdx | 211 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 221 insertions(+) create mode 100644 docs/migrations/26-10.mdx diff --git a/docs/migrations/25-10.mdx b/docs/migrations/25-10.mdx index 333ff9f7cf..b409976e50 100644 --- a/docs/migrations/25-10.mdx +++ b/docs/migrations/25-10.mdx @@ -279,6 +279,10 @@ This feature addresses previous inconsistencies in timestamp representations. - The `nextflow.config.schema` package was renamed to `nextflow.config.spec`. Plugin developers that define custom [configuration scopes][dev-plugins-extension-points-config] will need to update their imports accordingly. +### Cache-breaking changes + +The commands of `eval` outputs are now included in the task hash. This fixes a bug where editing an `eval` command did not re-execute the task. However, every process with an `eval` output will be re-executed on the first resume after upgrading. + ## Deprecations - The legacy type detection of CLI parameters is disabled when using the strict parser (`NXF_SYNTAX_PARSER=v2`). [Legacy parameters][workflow-params-legacy] should not rely on legacy type detection. Alternatively, use the new `params` block to convert CLI parameters based on their type annotations. Legacy type detection can be disabled globally by setting the environment variable `NXF_DISABLE_PARAMS_TYPE_DETECTION=true`. diff --git a/docs/migrations/26-04.mdx b/docs/migrations/26-04.mdx index 6b4b842b10..daefa63bd0 100644 --- a/docs/migrations/26-04.mdx +++ b/docs/migrations/26-04.mdx @@ -402,6 +402,12 @@ A Platform access token with appropriate permissions is required to download non - The [strict syntax parser][strict-syntax-page] is now enabled by default. The legacy parser can be enabled by setting the `NXF_SYNTAX_PARSER` environment variable to `v1`. +### Cache-breaking changes + +Maps are hashed differently. The hash now includes both map keys and values, where before it included only the values. + +This fixes a bug where changing a map input to a task did not re-execute it. However, any process with a map input will be re-executed on the first resume after upgrading. + ## Deprecations - The `nextflow.enable.strict` feature flag is deprecated. It is not needed when using the [strict parser][strict-syntax-page]. diff --git a/docs/migrations/26-10.mdx b/docs/migrations/26-10.mdx new file mode 100644 index 0000000000..fce01b111c --- /dev/null +++ b/docs/migrations/26-10.mdx @@ -0,0 +1,211 @@ +--- +title: Migrating to 26.10 +description: Review new features, breaking changes, and deprecations introduced in Nextflow 26.10. +--- + +# Migrating to 26.10 + +[Nextflow 26.10](https://github.com/nextflow-io/nextflow/releases/tag/v26.10.0) is scheduled to release in October 2026. + +## New features + +### Global cache + +The global cache is a cross-pipeline cache backed by cloud object storage, where the work directory itself is the shared, content-addressable cache. It is enabled using the `globalCache` config scope: + +```groovy +globalCache.enabled = true +globalCache.path = 's3://bucket/cache' +``` + +When the global cache is enabled, tasks are not isolated by run, allowing them to be reused across different runs. + +Read-only secondary caches can be consulted on a primary miss with `globalCache.secondaryPaths`. The first hit is reused in place and nothing is written back. + +Supported on Amazon S3, Azure Blob Storage, and Google Cloud Storage. + +### Static typing (out of preview) + +[Static typing][static-typing], introduced in Nextflow 25.10 as a preview feature, has been brought out of preview. + +The `nextflow.enable.types` flag is still required in every script that uses typed processes or workflows. Nextflow (`nextflow lint` and `nextflow run`) now performs type checking on scripts that enable this flag. + +### Workflow modules + +The [module system][module-registry] now supports workflows as well as processes. + +A module is a standalone process or a standalone workflow. A workflow module can be published to the Nextflow registry, installed, and included using the same commands and include syntax: + +```nextflow +// process module +include { BWA_MEM } from 'nf-core/bwa/mem' + +// workflow module +include { FASTQ_ALIGN_STAR } from 'nf-core/fastq_align_star' +``` + +A workflow module can depend on other modules by declaring them in the module spec and including them in the module script. When a workflow module is installed, it vendors its dependencies under its own `modules` directory, so two workflows can depend on different versions of the same module without conflict. + +A typed workflow module can be executed directly with `nextflow module run`: + +```bash +# create a typed workflow module +nextflow module create -kind Workflow acme/hello + +# run the workflow module +nextflow module run acme/hello --greeting 'Hello world!' +``` + +Each `take:` input becomes a param of the same name, and its declared type determines how the value is read. Each `emit:` output is reported as a workflow output. + +See [Modules][module-registry] for details. + +### Pipeline composition + +A pipeline can now be included and called like a named workflow, allowing you to compose pipelines with regular dataflow logic. + +Given a pipeline that declares a `params` block, an entry workflow, and an `output` block: + +```nextflow +// pipelines/rnaseq.nf +params { + input: Path + aligner: String = 'star_salmon' + fasta: Path +} + +workflow { + // ... +} + +output { + bams: Channel { path 'bams' } + multiqc: Path { path 'multiqc' } +} +``` + +Include it with the `workflow` keyword and call it by name: + +```nextflow +// main.nf +include { workflow as RNASEQ } from './pipelines/rnaseq.nf' + +workflow { + rnaseq = RNASEQ( + input: file('input.csv'), + fasta: file('index.fasta') + ) + rnaseq.bams.view() // Channel + rnaseq.multiqc.view() // Value +} +``` + +The included pipeline runs in the same session, the same DAG, and the same work directory as the including pipeline. The `params` block becomes the `take:` section and the `output` block becomes the `emit:` section. Outputs are channels and dataflow values, so a downstream pipeline can process upstream outputs as they are emitted. + +### Agents (preview) + +:::warning +Agents are a preview feature. Their syntax and behavior may change in future releases. +::: + +An agent is a process-shaped primitive that wraps an agent run. It declares typed inputs and outputs, renders a prompt, calls a language model, optionally lets the model call Nextflow modules as tools, and emits the result: + +```groovy +// nextflow.config +agent.runner = 'pi' +``` + +```nextflow +agent qa { + model 'openai/gpt-5-mini' + instruction 'You are a concise scientific assistant.' + + input: + question: String + + output: + answer: String + + prompt: + """ + Answer briefly: ${question} + """ +} + +workflow { + qa('What is FASTQ format?').view() +} +``` + +Each invocation runs as an ordinary Nextflow task with a work directory, retries, parallelism, caching, and lineage. Agents require a runner plugin: `nf-agent` calls the model from the driver JVM, `nf-agent-pi` runs the agent in a container using [Pi](https://pi.dev/). + +See [Agents][agent-page] for details. + +## Enhancements + +### Formatter preserves comments + +The Nextflow formatter (`nextflow lint -format`) now preserves all comments in scripts and config files. Previously, comments were preserved only in specific locations, otherwise they were discarded. + +### `logfile` command + +The new `logfile` command prints a `.nextflow.log` file, with optional level filtering and follow mode: + +```console +$ nextflow logfile kickass_rutherford -level ERROR +$ nextflow logfile last -f +``` + +The argument can be a run name, a session id or a unique prefix of one, the literal `last`, or a path to a log file. + +See the [`logfile`][cli-logfile] command reference for details. + +### Accelerator directive for local executor + +The local executor now allocates accelerators such as GPUs to tasks that request them with the `accelerator` directive. Set the environment variable for your accelerator type to declare which devices are available. See [Local executor][executor-local] for details. + +### Configurable plugin registries + +Nextflow resolves plugins from the public registry at `https://registry.nextflow.io` by default. Additional registries can now be configured through the `registry` config scope, and are tried in order. See [Plugin registry][plugin-registry] for details. + +### smolvm container engine + +Nextflow can run tasks in [smolvm](https://github.com/smol-machines/smolvm) microVMs. See [smolvm][container-smolvm] for details. + +## Breaking changes + +- The `echo` process directive was removed. Use `debug` instead. + +- The Kubernetes executor uses Jobs by default instead of Pods. Set [`k8s.computeResourceType`][config-k8s-computeResourceType] to `Pod` to keep the previous behavior. + +- Nextflow console output is written to standard error instead of standard output, so that the output of commands such as `nextflow inspect` and `nextflow run -output-format json` is not mixed with log messages. + +### Cache-breaking changes + +The hash function for `eval` commands was changed. This fixes a bug where tasks with `eval` outputs did not have a stable hash across runs. However, every process with an `eval` output will be re-executed on the first resume after upgrading. + +## Deprecations + +- The `storeDir` process directive is deprecated. Use explicit workflow logic to reuse an intermediate output if it is present and compute it otherwise. See [`storeDir`][process-storeDir] for an example. + +## Miscellaneous + +- New config option: [`apptainer.resourceLimits`][config-apptainer-resourceLimits] +- New config option: [`docker.cpuLimits`][config-docker-cpuLimits] +- New config option: [`manifest.diagram`][config-manifest-diagram] +- New config option: [`singularity.resourceLimits`][config-singularity-resourceLimits] + +[agent-page]: ../agent +[cli-logfile]: ../reference/cli/logfile +[config-apptainer-resourceLimits]: ../reference/config/apptainer#apptainerresourcelimits +[config-docker-cpuLimits]: ../reference/config/docker#dockercpulimits +[config-globalcache]: ../reference/config/globalcache +[config-k8s-computeResourceType]: ../reference/config/k8s#k8scomputeresourcetype +[config-manifest-diagram]: ../reference/config/manifest#manifestdiagram +[config-singularity-resourceLimits]: ../reference/config/singularity#singularityresourcelimits +[container-smolvm]: ../container/smolvm +[executor-local]: ../executor/local#accelerators +[module-registry]: ../modules +[plugin-registry]: ../plugins/plugin-registry#configuring-plugin-registries +[process-storeDir]: ../reference/process/directives/store-dir +[static-typing]: ../static-typing From fa2fc8e9e046c8a0d49581fb57c089b6877ae035 Mon Sep 17 00:00:00 2001 From: Ben Sherman Date: Fri, 18 Sep 2026 10:08:28 -0500 Subject: [PATCH 2/7] Add breaking-change note for the weblog option Assisted-by: Claude Code (Opus 5) Signed-off-by: Ben Sherman --- docs/migrations/26-10.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/migrations/26-10.mdx b/docs/migrations/26-10.mdx index fce01b111c..2b347ebe09 100644 --- a/docs/migrations/26-10.mdx +++ b/docs/migrations/26-10.mdx @@ -174,6 +174,8 @@ Nextflow can run tasks in [smolvm](https://github.com/smol-machines/smolvm) micr ## Breaking changes +- The `-with-weblog` run option is no longer supported. Use the [nf-weblog](https://github.com/nextflow-io/nf-weblog) plugin instead. + - The `echo` process directive was removed. Use `debug` instead. - The Kubernetes executor uses Jobs by default instead of Pods. Set [`k8s.computeResourceType`][config-k8s-computeResourceType] to `Pod` to keep the previous behavior. From 704abfe0bd12bed0de7ae570d1b0c1b5ff3c26c8 Mon Sep 17 00:00:00 2001 From: Ben Sherman Date: Sat, 19 Sep 2026 07:01:09 -0500 Subject: [PATCH 3/7] Remove global cache section Signed-off-by: Ben Sherman --- docs/migrations/26-10.mdx | 15 --------------- 1 file changed, 15 deletions(-) diff --git a/docs/migrations/26-10.mdx b/docs/migrations/26-10.mdx index 2b347ebe09..5764c992a2 100644 --- a/docs/migrations/26-10.mdx +++ b/docs/migrations/26-10.mdx @@ -9,21 +9,6 @@ description: Review new features, breaking changes, and deprecations introduced ## New features -### Global cache - -The global cache is a cross-pipeline cache backed by cloud object storage, where the work directory itself is the shared, content-addressable cache. It is enabled using the `globalCache` config scope: - -```groovy -globalCache.enabled = true -globalCache.path = 's3://bucket/cache' -``` - -When the global cache is enabled, tasks are not isolated by run, allowing them to be reused across different runs. - -Read-only secondary caches can be consulted on a primary miss with `globalCache.secondaryPaths`. The first hit is reused in place and nothing is written back. - -Supported on Amazon S3, Azure Blob Storage, and Google Cloud Storage. - ### Static typing (out of preview) [Static typing][static-typing], introduced in Nextflow 25.10 as a preview feature, has been brought out of preview. From 0a548229047955476a48d0eec50154c0a4bd8408 Mon Sep 17 00:00:00 2001 From: Ben Sherman Date: Thu, 1 Oct 2026 16:24:02 -0500 Subject: [PATCH 4/7] Update 26.10 migration notes for merged roadmap features Workflow modules, pipeline composition, and static typing out of preview are now merged, so describe them as implemented rather than as proposed. Restore a brief global cache section, and add the enhancements, deprecations, and config options from the 26.09 edge releases. Signed-off-by: Ben Sherman --- docs/migrations/26-10.mdx | 105 ++++++++++++++++++++++++++++++++------ 1 file changed, 89 insertions(+), 16 deletions(-) diff --git a/docs/migrations/26-10.mdx b/docs/migrations/26-10.mdx index 5764c992a2..ff1e97ceee 100644 --- a/docs/migrations/26-10.mdx +++ b/docs/migrations/26-10.mdx @@ -9,11 +9,19 @@ description: Review new features, breaking changes, and deprecations introduced ## New features +### Global cache + +The global cache is a shared, content-addressable cache backed by cloud storage. It stores all task executions in a single work directory. Whereas `-resume` only reuses work from a previous run of the same pipeline, the global cache can reuse tasks across different runs. + +The global cache is available through Seqera Platform. It supports AWS, Google Cloud, and Azure. + ### Static typing (out of preview) -[Static typing][static-typing], introduced in Nextflow 25.10 as a preview feature, has been brought out of preview. +[Static typing][static-typing], introduced in Nextflow 25.10 as a preview feature, has been brought out of preview. The syntax is unchanged since 26.04. This release brings type checking to the Nextflow CLI in addition to the language server. + +`nextflow lint` reports type errors for any script that enables `nextflow.enable.types`. `nextflow run` warns when type errors are found, but does not fail the run. -The `nextflow.enable.types` flag is still required in every script that uses typed processes or workflows. Nextflow (`nextflow lint` and `nextflow run`) now performs type checking on scripts that enable this flag. +The `nextflow.enable.types` flag is still required in every script that uses typed processes or typed workflows. ### Workflow modules @@ -29,7 +37,7 @@ include { BWA_MEM } from 'nf-core/bwa/mem' include { FASTQ_ALIGN_STAR } from 'nf-core/fastq_align_star' ``` -A workflow module can depend on other modules by declaring them in the module spec and including them in the module script. When a workflow module is installed, it vendors its dependencies under its own `modules` directory, so two workflows can depend on different versions of the same module without conflict. +A workflow module can depend on other modules by declaring them in the module spec and including them in the module script. When a workflow module is installed, it vendors its dependencies under its own `modules` directory, so two workflows can depend on different versions of the same module without conflict. Edit the declared versions in `meta.yml` and re-vendor them with `module install -update-deps`. A typed workflow module can be executed directly with `nextflow module run`: @@ -41,20 +49,22 @@ nextflow module create -kind Workflow acme/hello nextflow module run acme/hello --greeting 'Hello world!' ``` -Each `take:` input becomes a param of the same name, and its declared type determines how the value is read. Each `emit:` output is reported as a workflow output. +Each `take:` input becomes a param of the same name, and its declared type determines how the value is read. A `Channel` input takes a samplesheet path, which Nextflow loads as a channel of records, validating and converting each row against the element type. The samplesheet can be CSV, JSON, or YAML. Each `emit:` output is reported as a workflow output. -See [Modules][module-registry] for details. +See [Modules][module-registry] and [Typed parameters][workflow-typed-params] for details. ### Pipeline composition -A pipeline can now be included and called like a named workflow, allowing you to compose pipelines with regular dataflow logic. +A pipeline -- the `params` block, entry workflow, and `output` block of a script -- can be included and called like a named workflow. The `params` block acts as the `take:` section and the `output` block acts as the `emit:` section. This way, you can compose pipelines with regular dataflow logic. -Given a pipeline that declares a `params` block, an entry workflow, and an `output` block: +Given a pipeline: ```nextflow // pipelines/rnaseq.nf +nextflow.enable.types = true + params { - input: Path + input: Channel aligner: String = 'star_salmon' fasta: Path } @@ -69,23 +79,30 @@ output { } ``` -Include it with the `workflow` keyword and call it by name: +Include it with the `workflow` keyword, name it with an alias, and call it with a record of params: ```nextflow // main.nf +nextflow.enable.types = true + include { workflow as RNASEQ } from './pipelines/rnaseq.nf' workflow { - rnaseq = RNASEQ( - input: file('input.csv'), + main: + rnaseq = RNASEQ(record( + input: channel.of( /* ... */ ), fasta: file('index.fasta') - ) + )) rnaseq.bams.view() // Channel rnaseq.multiqc.view() // Value } ``` -The included pipeline runs in the same session, the same DAG, and the same work directory as the including pipeline. The `params` block becomes the `take:` section and the `output` block becomes the `emit:` section. Outputs are channels and dataflow values, so a downstream pipeline can process upstream outputs as they are emitted. +The `rnaseq.nf` pipeline can be run directly from the CLI or included like a named workflow. When included, the pipeline can consume a channel from an upstream pipeline, allowing it to process each item as soon as it is emitted. + +Both the calling script and the included pipeline must enable static typing. + +See [Pipeline composition][pipeline-composition] for details. ### Agents (preview) @@ -93,7 +110,7 @@ The included pipeline runs in the same session, the same DAG, and the same work Agents are a preview feature. Their syntax and behavior may change in future releases. ::: -An agent is a process-shaped primitive that wraps an agent run. It declares typed inputs and outputs, renders a prompt, calls a language model, optionally lets the model call Nextflow modules as tools, and emits the result: +An agent is a process-shaped primitive that wraps an agent run. It declares inputs and outputs, renders a prompt, calls a language model, and emits the result: ```groovy // nextflow.config @@ -122,7 +139,7 @@ workflow { } ``` -Each invocation runs as an ordinary Nextflow task with a work directory, retries, parallelism, caching, and lineage. Agents require a runner plugin: `nf-agent` calls the model from the driver JVM, `nf-agent-pi` runs the agent in a container using [Pi](https://pi.dev/). +Each invocation runs as an ordinary Nextflow task with a work directory, retries, parallelism, caching, and lineage. Agents can be composed like processes with regular dataflow logic. See [Agents][agent-page] for details. @@ -149,6 +166,38 @@ See the [`logfile`][cli-logfile] command reference for details. The local executor now allocates accelerators such as GPUs to tasks that request them with the `accelerator` directive. Set the environment variable for your accelerator type to declare which devices are available. See [Local executor][executor-local] for details. +### Publish targets as a map + +The `path` directive of a workflow output can return a map of source files to publish targets, which is equivalent to using the `>>` operator for each pair: + +```nextflow +output { + samples { + path { sample -> [ + (sample.fastq_1): "fastq/${sample.id}/", + (sample.fastq_2): "fastq/${sample.id}/" + ] } + } +} +``` + +This way, the publish mapping can be extracted to a shared function, e.g., for pipeline composition. + +See [Workflow outputs][workflow-output-def] for details. + +### Reports in the output directory + +The DAG, execution report, timeline, and trace file can be saved to the workflow output directory instead of the launch directory, using the new `directory` option in each scope: + +```groovy +report { + enabled = true + directory = 'pipeline_info' +} +``` + +The path is resolved against `outputDir` and must be a relative path within it. + ### Configurable plugin registries Nextflow resolves plugins from the public registry at `https://registry.nextflow.io` by default. Additional registries can now be configured through the `registry` config scope, and are tried in order. See [Plugin registry][plugin-registry] for details. @@ -175,24 +224,48 @@ The hash function for `eval` commands was changed. This fixes a bug where tasks - The `storeDir` process directive is deprecated. Use explicit workflow logic to reuse an intermediate output if it is present and compute it otherwise. See [`storeDir`][process-storeDir] for an example. +- The [`seqera.executor.autoLabels`][config-seqera-executor-autoLabels] config option is deprecated. Use [`tower.autoLabels`][config-tower-autoLabels] instead, which applies to every executor that supports the `resourceLabels` directive. + +- Machine type selection for Google Batch through the Seqera Cloud Info service is deprecated, along with the [`NXF_CLOUDINFO_ENABLED`][env-vars-NXF_CLOUDINFO_ENABLED] environment variable. + ## Miscellaneous - New config option: [`apptainer.resourceLimits`][config-apptainer-resourceLimits] +- New config option: [`azure.batch.pools..allowUnverifiedImages`][config-azure-batch-pools-allowUnverifiedImages] +- New config option: [`azure.batch.pools..virtualMachineImageId`][config-azure-batch-pools-virtualMachineImageId] +- New config option: [`dag.directory`][config-dag-directory] - New config option: [`docker.cpuLimits`][config-docker-cpuLimits] - New config option: [`manifest.diagram`][config-manifest-diagram] +- New config option: [`report.directory`][config-report-directory] +- New config option: [`seqera.executor.machineRequirement.onDemandCostRatio`][config-seqera-executor-onDemandCostRatio] - New config option: [`singularity.resourceLimits`][config-singularity-resourceLimits] +- New config option: [`timeline.directory`][config-timeline-directory] +- New config option: [`tower.autoLabels`][config-tower-autoLabels] +- New config option: [`trace.directory`][config-trace-directory] [agent-page]: ../agent [cli-logfile]: ../reference/cli/logfile [config-apptainer-resourceLimits]: ../reference/config/apptainer#apptainerresourcelimits +[config-azure-batch-pools-allowUnverifiedImages]: ../reference/config/azure#azurebatchpoolsnameallowunverifiedimages +[config-azure-batch-pools-virtualMachineImageId]: ../reference/config/azure#azurebatchpoolsnamevirtualmachineimageid +[config-dag-directory]: ../reference/config/dag#dagdirectory [config-docker-cpuLimits]: ../reference/config/docker#dockercpulimits -[config-globalcache]: ../reference/config/globalcache [config-k8s-computeResourceType]: ../reference/config/k8s#k8scomputeresourcetype [config-manifest-diagram]: ../reference/config/manifest#manifestdiagram +[config-report-directory]: ../reference/config/report#reportdirectory +[config-seqera-executor-autoLabels]: ../reference/config/seqera#seqeraexecutorautolabels +[config-seqera-executor-onDemandCostRatio]: ../reference/config/seqera#seqeraexecutormachinerequirementondemandcostratio [config-singularity-resourceLimits]: ../reference/config/singularity#singularityresourcelimits +[config-timeline-directory]: ../reference/config/timeline#timelinedirectory +[config-tower-autoLabels]: ../reference/config/tower#towerautolabels +[config-trace-directory]: ../reference/config/trace#tracedirectory [container-smolvm]: ../container/smolvm +[env-vars-NXF_CLOUDINFO_ENABLED]: ../reference/env-vars#nxf_cloudinfo_enabled [executor-local]: ../executor/local#accelerators [module-registry]: ../modules +[pipeline-composition]: ../workflow-typed#pipeline-composition [plugin-registry]: ../plugins/plugin-registry#configuring-plugin-registries [process-storeDir]: ../reference/process/directives/store-dir [static-typing]: ../static-typing +[workflow-output-def]: ../workflow#outputs +[workflow-typed-params]: ../typed-parameters From c2c32246d344d8e6060e9c62db4d76ffb5ebdc64 Mon Sep 17 00:00:00 2001 From: Ben Sherman Date: Thu, 1 Oct 2026 16:24:02 -0500 Subject: [PATCH 5/7] Document samplesheet channel params in the static typing docs Restore the samplesheet section of the static typing migration tutorial, modeling the input as a channel of records (Channel) now that channel params can be loaded from a samplesheet file. Also fix the preceding splitCsv example, which indexed the samplesheet positionally while the file has a header row, and add a preview note to the static typing overview. Signed-off-by: Ben Sherman --- docs/static-typing.mdx | 6 ++ docs/tutorials/static-types.mdx | 100 ++++++++++++++++++-------------- 2 files changed, 63 insertions(+), 43 deletions(-) diff --git a/docs/static-typing.mdx b/docs/static-typing.mdx index aace04244c..fb5dbfbef3 100644 --- a/docs/static-typing.mdx +++ b/docs/static-typing.mdx @@ -5,6 +5,10 @@ description: Overview of static typing in Nextflow, including typed processes, t # Static typing + +Static typing is available as a preview in Nextflow [25.10][static-typing-first-preview] and [26.04][static-typing-second-preview]. + + Static typing lets you model and validate the structure of your data as it flows through a pipeline. You add [standard Nextflow types][stdlib-types] to inputs and outputs at every level, from pipeline parameters to process and workflow outputs. Nextflow uses those annotations to catch type-related errors at compile-time. :::note @@ -68,6 +72,8 @@ Static typing builds on functionality documented in other sections: [migrating-static-types-operators]: ./tutorials/static-types-operators [preparing-static-types]: ./tutorials/static-types#preparing-for-static-typing [process-typed-page]: ./process-typed +[static-typing-first-preview]: ./migrations/25-10#static-typing-preview +[static-typing-second-preview]: ./migrations/26-04#static-typing-preview [stdlib-types]: ./reference/stdlib-types [strict-syntax-page]: ./strict-syntax [syntax-output-block]: ./reference/syntax#output-block diff --git a/docs/tutorials/static-types.mdx b/docs/tutorials/static-types.mdx index d2abf41c1f..73c7daf322 100644 --- a/docs/tutorials/static-types.mdx +++ b/docs/tutorials/static-types.mdx @@ -100,28 +100,29 @@ To migrate the pipeline parameters, use the schema and legacy parameters to defi ```nextflow params { // The input read-pair files - reads: String = "${projectDir}/data/ggal/ggal_gut_{1,2}.fq" + reads: String // The input transcriptome file - transcriptome: Path = "${projectDir}/data/ggal/ggal_1_48850000_49020000.Ggal71.500bpflank.fa" + transcriptome: Path // The output directory where the results will be saved - outdir: Path = 'results' + outdir: String = 'results' // Directory containing the configuration for MultiQC multiqc: Path = "${projectDir}/multiqc" } ``` -See [Parameters][workflow-typed-params] for more information about the `params` block. +Specify the test data defaults in the config file: -:::note -Parameters used only in the config file should be declared in the config, not in the script. Since rnaseq-nf has no such parameters, all parameters are declared in the script. See [Parameters][config-params] for more information. -::: +```groovy +params.reads = "${projectDir}/data/ggal/ggal_gut_{1,2}.fq" +params.transcriptome = "${projectDir}/data/ggal/ggal_1_48850000_49020000.Ggal71.500bpflank.fa" +``` -:::tip -The rnaseq-nf pipeline initializes the `reads` and `transcriptome` parameters to a test dataset by default, as it is designed as a toy example. In practice, defaults for test data should be defined in a config profile (e.g., `test`). -::: +The config file should declare parameters that are only used by the config. It can also specify overrides for script parameters, ideally in a config profile (e.g., `test`). Since rnaseq-nf is a toy example, it uses the test data by default. + +See [Typed parameters][typed-parameters-page] and [Config parameters][config-params] for more information. ### Loading a samplesheet input @@ -151,22 +152,56 @@ Refactor `params.reads` to refer to the samplesheet file path instead of a glob ```nextflow params { // The input samplesheet of paired-end reads - reads: Path = "${projectDir}/data/allreads.csv" + reads: Path // ... } ``` +```groovy +params.reads = "${projectDir}/data/allreads.csv" +params.transcriptome = // ... +``` + Refactor the `read_pairs_ch` to load the samplesheet as a channel of records: ```nextflow read_pairs_ch = channel.of(params.reads) - .flatMap { csv -> csv.splitCsv() } + .flatMap { csv -> csv.splitCsv(header: true) } .map { row -> - record(id: row[0], fastq_1: file(row[1]), fastq_2: file(row[2])) + record(id: row.id, fastq_1: file(row.fastq_1), fastq_2: file(row.fastq_2)) } ``` + + +A samplesheet input can be modeled as a channel of records instead of a file path. This approach simplifies the pipeline code and supports [pipeline composition][pipeline-composition], where a calling pipeline supplies the input from dataflow logic instead of a file. + +Refactor `params.reads` as a channel of records: + +```nextflow +params { + // The input samplesheet of paired-end reads + reads: Channel + + // ... +} + +record Sample { + id: String + fastq_1: Path + fastq_2: Path +} +``` + +In the above, `Sample` is a *record type* based on the samplesheet structure. When a file path is supplied to a channel-type parameter (e.g., `Channel`), the file is automatically loaded and each row is validated against and converted to the element type. + +Nextflow now loads the samplesheet automatically, so `params.reads` completely replaces `read_pairs_ch`. + +:::note +Channel params can also be loaded from JSON and YAML samplesheets. See [Typed parameters][typed-parameters-page] for more information. +::: + ### Migrating processes See [Typed processes][process-typed-page] for an overview of typed processes. @@ -390,13 +425,7 @@ You can infer the type of each workflow input by examining how the workflow is c ```nextflow workflow { - read_pairs_ch = channel.of(params.reads) - .flatMap { csv -> csv.splitCsv() } - .map { row -> - record(id: row[0], fastq_1: file(row[1]), fastq_2: file(row[2])) - } - - RNASEQ(read_pairs_ch, params.transcriptome) + RNASEQ(params.reads, params.transcriptome) // ... } @@ -404,9 +433,9 @@ workflow { You can determine the type of each input as follows: -- The channel `read_pairs_ch` has type `Channel`, where each record contains the fields `id`, `fastq_1`, `fastq_2`. +- The parameter `params.reads` is declared in the `params` block as `Channel`. -- The parameter `params.transcriptome` has type `Path` as defined in the `params` block. +- The parameter `params.transcriptome` is declared in the `params` block as `Path`. Specify the workflow input types as follows: @@ -420,12 +449,6 @@ workflow RNASEQ { // ... } - -record Sample { - id: String - fastq_1: Path - fastq_2: Path -} ``` The `read_pairs_ch` channel also needs to provide all of the record fields required by downstream processes. It is used by `FASTQC` and `QUANT`, which both declare the following record input: @@ -515,11 +538,7 @@ The entry workflow is defined as follows: ```nextflow workflow { - read_pairs_ch = channel.of(params.reads) - .flatMap { csv -> csv.splitCsv() } - .map { row -> - record(id: row[0], fastq_1: file(row[1]), fastq_2: file(row[2])) - } + read_pairs_ch = channel.fromFilePairs(params.reads, checkIfExists: true, flat: true) (fastqc_ch, quant_ch) = RNASEQ(read_pairs_ch, params.transcriptome) @@ -535,13 +554,7 @@ Rewrite this workflow based on the updated params, processes, and subworkflows: nextflow.enable.types = true workflow { - read_pairs_ch = channel.of(params.reads) - .flatMap { csv -> csv.splitCsv() } - .map { row -> - record(id: row[0], fastq_1: file(row[1]), fastq_2: file(row[2])) - } - - samples_ch = RNASEQ(read_pairs_ch, params.transcriptome) + samples_ch = RNASEQ(params.reads, params.transcriptome) multiqc_files_ch = samples_ch .flatMap { id, fastqc, quant -> [fastqc, quant] } @@ -551,7 +564,7 @@ workflow { } ``` -The `reads` param was refactored as a `Path`, so it is loaded into a channel of records using `splitCsv`. It is compatible with the records expected by `RNASEQ`. +The `reads` param was refactored as a channel of records, so it can be passed directly to `RNASEQ`. It is compatible with the records expected by `RNASEQ`. The `RNASEQ` workflow now returns a single combined channel, so the `mix` operation is no longer needed. The `flatMap` operator is used to extract the files from each record in `samples_ch`. @@ -718,16 +731,17 @@ See the following links to learn more about static typing: [migrating-workflow-outputs]: ./workflow-outputs [operator-combine]: ../reference/operator#combine [operator-page]: ../reference/operator +[pipeline-composition]: ../workflow-typed#pipeline-composition [process-input-each]: ../process#input-repeaters-each [process-reference-typed]: ../reference/process/inputs-outputs-typed [process-typed-page]: ../process-typed [rnaseq-nf-page]: ./rnaseq-nf -[script-records]: ../script#records +[script-records]: ../script#records-and-tuples [strict-syntax-deprecated]: ../strict-syntax#deprecated-syntax [strict-syntax-page]: ../strict-syntax [stdlib-types]: ../reference/stdlib-types [stdlib-types-path]: ../reference/stdlib-types/path [syntax-record-type]: ../reference/syntax#record-type +[typed-parameters-page]: ../typed-parameters [workflow-special-operators]: ../workflow#dataflow [workflow-typed-page]: ../workflow-typed -[workflow-typed-params]: ../workflow#parameters From 0c01f37b5a7f5fc785382cc5c1eb79626793f06c Mon Sep 17 00:00:00 2001 From: Ben Sherman Date: Fri, 2 Oct 2026 05:02:58 -0500 Subject: [PATCH 6/7] Apply batched suggestions from review [ci fast] Co-authored-by: Chris Hakkaart Signed-off-by: Ben Sherman --- docs/migrations/26-10.mdx | 36 ++++++++++++++++----------------- docs/tutorials/static-types.mdx | 4 ++-- 2 files changed, 20 insertions(+), 20 deletions(-) diff --git a/docs/migrations/26-10.mdx b/docs/migrations/26-10.mdx index ff1e97ceee..4a09f24394 100644 --- a/docs/migrations/26-10.mdx +++ b/docs/migrations/26-10.mdx @@ -17,17 +17,17 @@ The global cache is available through Seqera Platform. It supports AWS, Google C ### Static typing (out of preview) -[Static typing][static-typing], introduced in Nextflow 25.10 as a preview feature, has been brought out of preview. The syntax is unchanged since 26.04. This release brings type checking to the Nextflow CLI in addition to the language server. +[Static typing][static-typing], introduced as a preview feature in Nextflow 25.10, is no longer in preview. The syntax has not changed since 26.04. Type checking is now available in the Nextflow CLI as well as the language server. -`nextflow lint` reports type errors for any script that enables `nextflow.enable.types`. `nextflow run` warns when type errors are found, but does not fail the run. +`nextflow lint` reports type errors for any script that enables `nextflow.enable.types`. `nextflow run` warns about type errors but does not fail the run. -The `nextflow.enable.types` flag is still required in every script that uses typed processes or typed workflows. +Every script that uses typed processes or typed workflows must still enable `nextflow.enable.types`. ### Workflow modules The [module system][module-registry] now supports workflows as well as processes. -A module is a standalone process or a standalone workflow. A workflow module can be published to the Nextflow registry, installed, and included using the same commands and include syntax: +A module is a standalone process or workflow. You publish workflow modules to the Nextflow registry, install them, and include them with the same commands and include syntax as process modules: ```nextflow // process module @@ -37,9 +37,9 @@ include { BWA_MEM } from 'nf-core/bwa/mem' include { FASTQ_ALIGN_STAR } from 'nf-core/fastq_align_star' ``` -A workflow module can depend on other modules by declaring them in the module spec and including them in the module script. When a workflow module is installed, it vendors its dependencies under its own `modules` directory, so two workflows can depend on different versions of the same module without conflict. Edit the declared versions in `meta.yml` and re-vendor them with `module install -update-deps`. +To depend on other modules, a workflow module declares them in the module spec and includes them in the module script. Installing a workflow module vendors its dependencies under its own `modules` directory. Two workflows can therefore depend on different versions of the same module without conflict. To change a dependency version, edit it in `meta.yml` and re-vendor the dependencies with `module install -update-deps`. -A typed workflow module can be executed directly with `nextflow module run`: +Run a typed workflow module directly with `nextflow module run`: ```bash # create a typed workflow module @@ -49,13 +49,13 @@ nextflow module create -kind Workflow acme/hello nextflow module run acme/hello --greeting 'Hello world!' ``` -Each `take:` input becomes a param of the same name, and its declared type determines how the value is read. A `Channel` input takes a samplesheet path, which Nextflow loads as a channel of records, validating and converting each row against the element type. The samplesheet can be CSV, JSON, or YAML. Each `emit:` output is reported as a workflow output. +Each `take:` input becomes a param of the same name. Its declared type determines how Nextflow reads the value. A `Channel` input takes a CSV, JSON, or YAML samplesheet. Nextflow loads the samplesheet as a channel of records and validates and converts each row against the element type. Nextflow reports each `emit:` output as a workflow output. See [Modules][module-registry] and [Typed parameters][workflow-typed-params] for details. ### Pipeline composition -A pipeline -- the `params` block, entry workflow, and `output` block of a script -- can be included and called like a named workflow. The `params` block acts as the `take:` section and the `output` block acts as the `emit:` section. This way, you can compose pipelines with regular dataflow logic. +You can include a pipeline and call it like a named workflow. Here, a pipeline is the `params` block, entry workflow, and `output` block of a script. The `params` block acts as the `take:` section and the `output` block acts as the `emit:` section. Use this to compose pipelines with regular dataflow logic. Given a pipeline: @@ -98,7 +98,7 @@ workflow { } ``` -The `rnaseq.nf` pipeline can be run directly from the CLI or included like a named workflow. When included, the pipeline can consume a channel from an upstream pipeline, allowing it to process each item as soon as it is emitted. +You can run `rnaseq.nf` directly from the CLI or include it like a named workflow. When included, it can consume a channel from an upstream pipeline and process each item as soon as the upstream pipeline emits it. Both the calling script and the included pipeline must enable static typing. @@ -139,7 +139,7 @@ workflow { } ``` -Each invocation runs as an ordinary Nextflow task with a work directory, retries, parallelism, caching, and lineage. Agents can be composed like processes with regular dataflow logic. +Each agent call runs as a regular Nextflow task, with its own work directory, retries, parallelism, caching, and lineage. You can compose agents with regular dataflow logic, like processes. See [Agents][agent-page] for details. @@ -147,7 +147,7 @@ See [Agents][agent-page] for details. ### Formatter preserves comments -The Nextflow formatter (`nextflow lint -format`) now preserves all comments in scripts and config files. Previously, comments were preserved only in specific locations, otherwise they were discarded. +The Nextflow formatter (`nextflow lint -format`) now preserves all comments in scripts and config files. Previously, the formatter discarded comments outside of specific locations. ### `logfile` command @@ -158,7 +158,7 @@ $ nextflow logfile kickass_rutherford -level ERROR $ nextflow logfile last -f ``` -The argument can be a run name, a session id or a unique prefix of one, the literal `last`, or a path to a log file. +The argument can be a run name, a session ID or a unique prefix of one, `last`, or a log file. See the [`logfile`][cli-logfile] command reference for details. @@ -168,7 +168,7 @@ The local executor now allocates accelerators such as GPUs to tasks that request ### Publish targets as a map -The `path` directive of a workflow output can return a map of source files to publish targets, which is equivalent to using the `>>` operator for each pair: +The `path` directive of a workflow output can return a map of source files to publish targets. This is equivalent to using the `>>` operator for each pair: ```nextflow output { @@ -181,13 +181,13 @@ output { } ``` -This way, the publish mapping can be extracted to a shared function, e.g., for pipeline composition. +You can extract the publish mapping to a shared function, e.g., to reuse it when composing pipelines. See [Workflow outputs][workflow-output-def] for details. ### Reports in the output directory -The DAG, execution report, timeline, and trace file can be saved to the workflow output directory instead of the launch directory, using the new `directory` option in each scope: +Use the new `directory` option in the `dag`, `report`, `timeline`, and `trace` scopes to save built-in reports to the workflow output directory instead of the launch directory: ```groovy report { @@ -200,7 +200,7 @@ The path is resolved against `outputDir` and must be a relative path within it. ### Configurable plugin registries -Nextflow resolves plugins from the public registry at `https://registry.nextflow.io` by default. Additional registries can now be configured through the `registry` config scope, and are tried in order. See [Plugin registry][plugin-registry] for details. +Nextflow resolves plugins from the public registry at `https://registry.nextflow.io` by default. Use the `registry` config scope to configure additional registries. Nextflow tries them in order. See [Plugin registry][plugin-registry] for details. ### smolvm container engine @@ -214,11 +214,11 @@ Nextflow can run tasks in [smolvm](https://github.com/smol-machines/smolvm) micr - The Kubernetes executor uses Jobs by default instead of Pods. Set [`k8s.computeResourceType`][config-k8s-computeResourceType] to `Pod` to keep the previous behavior. -- Nextflow console output is written to standard error instead of standard output, so that the output of commands such as `nextflow inspect` and `nextflow run -output-format json` is not mixed with log messages. +- Nextflow writes console output to standard error instead of standard output. This separates log messages from the output of commands such as `nextflow config` and `nextflow run -output-format json`. ### Cache-breaking changes -The hash function for `eval` commands was changed. This fixes a bug where tasks with `eval` outputs did not have a stable hash across runs. However, every process with an `eval` output will be re-executed on the first resume after upgrading. +The hash of `eval` commands has changed. This fixes a bug where tasks with `eval` outputs did not have a stable hash across runs. As a result, every process with an `eval` output re-executes on the first resume after upgrading. ## Deprecations diff --git a/docs/tutorials/static-types.mdx b/docs/tutorials/static-types.mdx index 73c7daf322..af900db61f 100644 --- a/docs/tutorials/static-types.mdx +++ b/docs/tutorials/static-types.mdx @@ -194,9 +194,9 @@ record Sample { } ``` -In the above, `Sample` is a *record type* based on the samplesheet structure. When a file path is supplied to a channel-type parameter (e.g., `Channel`), the file is automatically loaded and each row is validated against and converted to the element type. +In this example, `Sample` is a *record type* that matches the samplesheet structure. When you supply a file path to a channel-type parameter (e.g., `Channel`), Nextflow loads the file and validates and converts each row against the element type. -Nextflow now loads the samplesheet automatically, so `params.reads` completely replaces `read_pairs_ch`. +Because Nextflow loads the samplesheet automatically, `params.reads` replaces `read_pairs_ch`. :::note Channel params can also be loaded from JSON and YAML samplesheets. See [Typed parameters][typed-parameters-page] for more information. From d3a909a89923797da5815fc75ab2cd768b4dfd69 Mon Sep 17 00:00:00 2001 From: Ben Sherman Date: Fri, 2 Oct 2026 05:12:40 -0500 Subject: [PATCH 7/7] Point the static typing tutorial at the static-typing branch The rnaseq-nf preview-26-04 branch was renamed to static-typing, since static typing is no longer a preview. Signed-off-by: Ben Sherman --- docs/tutorials/static-types.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/static-types.mdx b/docs/tutorials/static-types.mdx index af900db61f..fa83a07a26 100644 --- a/docs/tutorials/static-types.mdx +++ b/docs/tutorials/static-types.mdx @@ -54,7 +54,7 @@ The approach is as follows: 3. Convert each process to static typing 4. Convert each workflow to static typing -The completed migration is available in the [preview-26-04](https://github.com/nextflow-io/rnaseq-nf/tree/preview-26-04) branch. +The completed migration is available in the [static-typing](https://github.com/nextflow-io/rnaseq-nf/tree/static-typing) branch. ### Migrating pipeline parameters