During the October 2026 nf-core hackathon, two hackathon groups joined forces to tackle the upcoming changes caused by the introduction of static typing and record types. The aim of the combined task force was to develop the nf-core guidelines related to these new Nextflow features.

This blog post gives an overview of all the upcoming changes to nf-core/modules along with the reasoning behind each one.

Warning

Static typing and record types have been pretty much stable since Nextflow 26.04.0. There are however some cases where possibly breaking bugs were patched in later versions. Keep an eye out for notes like this throughout the blog post to know in what versions the bugs for that specific section were fixed.

Meme photo based on the TV show Community, where one character comes into a room holding a stack of picture boxes, they are captioned with “Random pipeline maintainer”. Underneath is a scene where one person is swinging a burning towel, they are captioned with “Records”. There is burning liquid on the floor captioned “static typing”. Two people kneeling aroudn a person shot in the leg, captioned “ext changes”. One more person is standing a bit in the background looking shot, captioned “when removed”.

Singular inputs and outputs

Previously, multiple channels and/or values were allowed in the input and output block of a process. In fact we even enforced that the output block must contain one output per file produced by the process. This will change now by requiring each module to take one Record as an input and to emit one Record as the output.

This change will be enforced due to many reasons, these are the most prominent ones:

  1. This will reduce large multiMap operations required to keep files in sync with the actual sample data.
  2. Having a single output with record types will make it easier to subset the record type and merge it back into another record type. This is especially useful for processes that emit a lot of files as there will be no need for multi-line joins anymore.
  3. Due to this, each sample travels through the pipeline as a single record that collects results at every process, making the dataflow much clearer.
Warning

Any records returned by a typed function (e.g. def f(x: Record) -> Record) have a different hash on every run, causing processes to never resume since they think the record is always different. This has been fixed in Nextflow 26.10.4 so it’s advised to use this or any later version if you use typed functions that return a Record type.

Composition of the input record type

The input record should consist of several required and optional typed fields.

  • A record type is a Map-like structure that consists of a predefined set of keys.
  • The record is not limited to only these keys, but it will validate if these keys exists (if needed) and if they have the right type.
  • To type a specific field, put a : followed by the expected type after the field key name.

A record with typed fields can look like this:

input:
record(
id: String,
input_file: Path,
input_index: Path?
)
Tip

To annotate a field as optional, put a ? after the type of that field (for example, input_index: Path? in the example above).

Read more about typing in the Nextflow docs.

One special case of typing is file inputs:

  • In the case that only one file is expected use the Path type
  • If multiple files are expected or possible, use one of the following depending on what the process needs:
    • Set<Path> if order does not matter and there are no duplicate paths. Use .toSet() to convert any iterable to a Set.
    • List<Path> if order does matter and there can be duplicate paths. Use .toSorted() to convert any iterable to a List.
    • Bag<Path> if order does not matter and there can be duplicate paths.

Picture from the movie Finding Nemo with several sea gulls looking into the camera captures with “types, types, types”

The input record type within an nf-core module should consist of the following fields:

  1. All required input values needed to run the process.
    • One big change compared to the previous nf-core/module specifications is that mandatory fields from the meta map should now also be values in the top-level of the record type.
    • This is the id field for every process and optionally single_end and strandedness wherever it is needed.
    • This will increase the transparency of each process meaning that it will no longer have a silent requirement on meta fields.
  2. All files (required and optional) that the process can use to run.
    • These should all have some variation of the Path type as described above.
  3. The meta Map will become the meta Record.
    • This field will now be fully optional and is mainly there to help pipeline developers pass additional pipeline-related information to the process.
    • This can be referenced by pipeline users in ext.args and will still be passed to the output so it is also available for downstream logic (like joining).
  4. Optional arguments strings.
    • There should be one argument string for every tool used by the process, for which the name should follow the following structure: <tool_name(_subtool_name)>_args (this is the same notation as for the module name, e.g samtools_sort_args).
    • This will replace the usage of ext.args for pipeline developers.
    • ext.args will still be available for pipeline users.
    • In case the same tool is used twice or more in a process, a number can be added after the tool name in the field name (e.g. samtools_sort1_args and samtools_sort2_args).
  5. The optional output_prefix field.
    • This field will replace the usage of ext.prefix for pipeline developers.
    • ext.prefix will still be available for pipeline users.
    • In the rare case that multiple prefixes are needed an additional output_prefix2 field can also be added.

The main logic behind most of these changes is to make the modules compatible with new and upcoming Nextflow features. Due to these changes a config file is no longer needed to configure the process properly. This makes the creation of meta pipelines a lot easier. Additionally, by removing the requirement of the meta Record, the usage of nextflow module run will also be a lot easier.

In case the inputs need to be staged, please move these to the new stage block of the process. More information on this can be found in the docs. The new stage block could now also be used to include script files into the module instead of relying on the bin folder or process templates. For example:

stage:
stageAs file("${moduleDir}/bin/template_script.py"), '*'
Warning

A bug was recently fixed where the staged files weren’t being accounted for in the process hash. This means that the process would still resume even though the script has been updated. This bug was patched in Nextflow version 26.10.6 and it’s highly advised to use this or higher versions if you want to stage scripts in this way.

Example

This example will show the changes that need to be done for the SAMTOOLS_STATS module.

This module takes two required files called input and input_index and two optional files called fasta and fai. These files are split over two input lines, that need to be merged into one record. meta2 is removed because the two optional files are now part of the main input entry. The id field has been added as a required value and the required meta Map was turned into an optional Record. Finally, samtools_stats_args and output_prefix have been added as optional String values.

The input section of a module will change like this:

input:
tuple val(meta), path(input), path(input_index)
tuple val(meta2), path(fasta), path(fai)
record(
id: String,
meta: Record?,
input: Path,
input_index: Path,
fasta: Path?,
fai: Path?,
samtools_stats_args: String?,
output_prefix: String?
)

So, with inputs out of the way, let’s move on to the module outputs!

Composition of the output record

The record definition in the output block is a bit different when compared to the record definition in the input block. There is no option to provide the expected type of the output since Nextflow already derives this based on the type of the value passed to each record field. Read more about this in the Nextflow docs

The output record should consist of the following fields:

  1. The id field given via the input record
  2. The meta Record given via the input record (this will be null in case no meta was passed)
  3. All possible file outputs of the process correctly configured using the file() or files() functions (this includes required and optional files, use optional: true for optional files)
  4. All version outputs should be moved to the topics block

Example

Let’s return to our previous example of SAMTOOLS_STATS and take a look at what needs to be done to update the output block of that module.

The module outputs one file called stats and one version of the samtools stats tool (as an output and a topic). In this case, no multiple outputs should be merged because the module only outputs one file. The id field was added to the output record, which directly uses the id value passed to the input of the module. Finally, the versions output has also been converted to a record type and has been moved to the topic block.

The output section of the module will change like this:

output:
tuple val(meta), path("*.stats"), emit: stats
tuple val("${task.process}"), val('samtools'), eval('samtools version | sed "1!d;s/.* //"'), emit: versions_samtools, topic: versions
record(
id: id,
meta: meta,
stats: file("*.stats")
)
topic:
record(process: "${task.process}", tool: 'samtools', version: eval('samtools version | sed "1!d;s/.* //"')) >> 'versions'

Changes to ext variables

As seen in the input of the module, some extra inputs were added that have a similar function to the current ext variables. Let’s take a look how to properly handle these variables after the migration.

Instead of defining the prefix and args variables in the script and stub block separately, prefix and args they must now be defined in a new block under the container declaration in the process code. This way the declaration happens only once in the process, making sure that there is more parity between the script and stub block.

The definition of these variables now also needs to take into account that the output_prefix and <tool>_args options are given in the input. This is the order of priority for each option where one of these variables can be declared (with the first one taking priority over all others, etc):

  1. The ext.<var> declaration in a configuration file passed by the pipeline user
  2. The value passed in the input record of the process by the pipeline developer
  3. The default of the value (for example id for the prefix)

ext.when should also be removed since it’s no longer supported in statically typed modules, the new process.when option can be used instead.

Warning

The process.when configuration option should only be reserved for pipeline users.

Pipeline developers should setup their logic in the workflow itself using if statements and channel operator logic.

Example

Let’s return to SAMTOOLS_STATS once again and take a look at how to handle the ext variables there.

The handling of ext variables will change like this:

process SAMTOOLS_STATS {
...
ext [
prefix: { output_prefix ?: "${id}" },
args: { samtools_stats_args ?: '' }
]
input:
...
output:
...
topic:
...
when: task.ext.when == null || task.ext.when
script:
def args = task.ext.args ?: ''
def prefix = task.ext.prefix ?: "${meta.id}"
def reference = fasta ? "--reference ${fasta}" : ""
"""
samtools \\
stats \\
${args} \\
${task.ext.args} \\
--threads ${task.cpus} \\
${reference} \\
${input} \\
> ${prefix}.stats
> ${task.ext.prefix}.stats
"""
stub:
def prefix = task.ext.prefix ?: "${meta.id}"
"""
touch ${prefix}.stats
touch ${task.ext.prefix}.stats
"""
}

Picture from the movie Toy story, where one child captioned “nf-core” drops a doll captioned “legacy processes” and the subtitle in the movie still reads “I don’t want to play with you anymore.”

Full example

This is full example of the SAMTOOLS_STATS module.

modules/nf-core/samtools/stats/main.nf
nextflow.enable.types = true
process SAMTOOLS_STATS {
tag "${id}"
label 'process_single'
conda "${moduleDir}/environment.yml"
container "${workflow.containerEngine in ['singularity', 'apptainer'] && !task.ext.singularity_pull_docker_container
? 'https://community-cr-prod.seqera.io/docker/registry/v2/blobs/sha256/e9/e994bf4eb3731150511a14f5706b7bdfd64df1b6d40898fff334286c027e0859/data'
: 'community.wave.seqera.io/library/htslib_samtools:1.24--d697cfb9dce007cd'}"
ext [
prefix: { output_prefix ?: "${id}" },
args: { samtools_stats_args ?: '' }
]
input:
record(
id: String,
meta: Record?,
input: Path,
input_index: Path,
fasta: Path?,
fai: Path?,
samtools_stats_args: String?,
output_prefix: String?
)
output:
record(
id: id,
meta: meta,
stats: file("*.stats", optional: true)
)
topic:
record(process: "${task.process}", tool: 'samtools', version: eval('samtools version | sed "1!d;s/.* //"')) >> 'versions'
script:
def reference = fasta ? "--reference ${fasta}" : ""
"""
samtools \\
stats \\
${task.ext.args} \\
--threads ${task.cpus} \\
${reference} \\
${input} \\
> ${task.ext.prefix}.stats
"""
stub:
"""
touch ${task.ext.prefix}.stats
"""
}

Conclusion

With the move to typed records we simplify the concept of nf-core modules: each modules takes one structured input and emits one structured output. Making required values explicit and separating module arguments from pipeline-user configuration will also make modules easier to reuse and compose. Migrating to these guidelines is a step towards more flexible and maintainable nf-core modules.


Published on
18 November 2026
Written by