Configuration of the nf-co2footprint plugin

General usage

To test if the plugin works on your system please follow the quick start guide (Quick Start) on a small pipeline like nextflow-io/hello. The current minimum version of Nextflow is 25.10.0.

To customize the plugin settings to your computing environment and preferences, you can adjust the nf-co2footprint plugin parameters in your config file as follows:

Example

nextflow.config

plugins {
  id 'nf-co2footprint@1.2.0'
}

// Optional example config settings for CO₂ reporting:

params {
  outdir = 'out'
  trace_report_suffix = new java.util.Date().format('yyyy-MM-dd_HH-mm-ss')
}

co2footprint {
  trace {
    file = "${params.outdir}/pipeline_info/co2footprint_trace_${params.trace_report_suffix}.txt"
  }

  summary {
    file = "${params.outdir}/pipeline_info/co2footprint_summary_${params.trace_report_suffix}.txt"
  }

  report {
    file = "${params.outdir}/pipeline_info/co2footprint_report_${params.trace_report_suffix}.html"
  }

  location = 'DE'                             // replace with your zone code
  emApiKey = secrets.EM_API_KEY               // set your API key as Nextflow secret with the name 'EM_API_KEY'
  pue = 1.3                                   // replace with PUE of your data center
  machineType = 'compute cluster'             // set to 'compute cluster', 'local', or 'cloud'
}

Include the config file for your pipeline run using the -c Nextflow parameter, for example as follows:

nextflow run nextflow-io/hello -c nextflow.config

For a complete list and detailed descriptions of all available configuration parameters, please refer to the Parameters section.

Carbon intensity (CI)

How are CI values determined by default?

The plugin can retrieve real-time carbon intensity (CI) values in grams of CO₂-equivalent per kilowatt-hour (gCO₂eq/kWh) from Electricity Maps if a valid API key and location are provided. This enables task-specific CI estimates based on the actual energy mix at execution time.
If no API key is supplied, the plugin will fall back to using 2024 yearly average values for the specified zone (if available). When no location is provided either, a global default CI value is used.

The logic applied in detail:

If ci is explicitly set, this value is used directly as the carbon intensity, and no API call is made.
If ci is not set, but both location and emApiKey are provided, the plugin will query the Electricity Maps API for a real-time carbon intensity value for the specified zone. The API call is made once per Nextflow task to retrieve the most up-to-date carbon intensity.
If only location is set, the plugin will fallback to a default value for the specified zone.
If neither ci nor valid location and apiKey are provided, the plugin will fallback to a global default value.

Carbon intensity data is retrieved from Electricity Maps and used under the Open Database License (ODbL). See the full attribution and license terms here.

Accounting for a personal energy mix (`ciMarket`)

The ciMarket parameter can be used to provide a custom value to account for differences to your regional average. This can occur due to:

A different market share through a contract with your energy provider, guaranteeing to provide a certain percentage of electricity from renewable sources
Direct contributions to the used electricity (e.g. via owned solar panels)

You can calculate an approximation of your personal/marked-based CI via the average of the emission factors weighted by their respective share in your mix.

Example: If your institution would produce half of their energy themselves through 20% hydroelectric and 80% solar power generation:

\[ \mathrm{ci}_{\mathrm{total}} = \left( \mathrm{ci}_{\mathrm{hydro}} \cdot 0.2 + \mathrm{ci}_{\mathrm{solar}} \cdot 0.8 \right) \cdot 0.5 + \mathrm{ci}_{\mathrm{region}} \cdot 0.5 \]

Reporting criteria of market-based emissions

Reporting a market-based carbon footprint is only encouraged when the market-based carbon intensity (CI) is temporally and spatially aligned with electricity consumption, as recommended by the GHG protocol.

This implies that the purchased and consumed electricity must be provided within the same hour and market region.

Cloud computations

While the nf-co2footprint plugin supports carbon footprint calculations for cloud instances, there are important limitations and configuration options to consider.

✅ What is supported automatically

Provider-specific default PUE values:
For common cloud platforms, the plugin automatically applies default Power Usage Effectiveness (PUE) values. For example, AWS uses a default PUE of 1.15.
See the full list of supported providers and their PUEs in the executor PUE mapping file.
Automatic AWS region detection:
When running on AWS (Batch, Fargate, EC2), the plugin can automatically detect your region and set the corresponding location for more accurate calculations.

Cloud limitations

Incomplete cloud-specific data:
Not all cloud environments are fully supported. Some values, such as specific CPU models or PUEs, may be missing from our datasets. Calculations may rely on fallback values in these cases.
Unsupported providers/platforms:
If your cloud provider or platform is not covered by the plugin’s defaults, you may need to supply additional information manually.

🛠️ What you can configure manually

To improve the accuracy of your CO₂ footprint estimates on the cloud, you are encouraged to provide:

The location of your instance
The ciMarket parameter if you know the carbon intensity (CI) of the energy mix used by your cloud instance
The PUE of the data center (cloud providers often give global averages)
CPU TDP values:
- If you have multiple CPU models, provide a customCpuTdpFile containing their TDP values.
- If you have only one CPU model and do not want to provide a table, set ignoreCpuModel = true and specify powerdrawCpuDefault.

For more information, see Parameters.

Example

nextflow_cloud.config

plugins {
  id 'nf-co2footprint@1.2.0'
}

params {
  outdir = 'out'
  trace_report_suffix = new java.util.Date().format('yyyy-MM-dd_HH-mm-ss')
}

co2footprint {
  trace {
    file = "${params.outdir}/pipeline_info/co2footprint_trace_${params.trace_report_suffix}.txt"
  }

  summary {
    file = "${params.outdir}/pipeline_info/co2footprint_summary_${params.trace_report_suffix}.txt"
  }

  report {
    file = "${params.outdir}/pipeline_info/co2footprint_report_${params.trace_report_suffix}.html"
  }

  location            = 'DE'
  emApiKey            = secrets.EM_API_KEY
  pue                 = 1.3
  ignoreCpuModel      = true
  powerdrawCpuDefault = 8
}

GPU computations

Warning

GPU support is not yet implemented. Tracking of GPU-driven computations may not work or may be incomplete.