ma/nextflow/docs/reference/env-vars.md

(config-env-vars)=

Environment variables

The following environment variables control the configuration of the Nextflow runtime and the underlying Java virtual machine.

Java settings

JAVA_CMD

Defines the path location of the Java binary command used to launch Nextflow.

JAVA_HOME

Defines the path location of the Java VM installation used to run Nextflow.

(nxf-env-vars)=

Nextflow settings

NXF_AGENT_MODE

:::{versionadded} 26.04.0 :::

When true, enables agent output mode. In this mode, Nextflow replaces the interactive ANSI log with minimal, structured output optimized for AI agents and non-interactive environments. The output uses tagged lines such as [PIPELINE], [PROCESS], [WARN], [ERROR], and [SUCCESS]/[FAILED] written to standard output (default: false).

NXF_ANSI_LOG

Enables/disables ANSI console output (default true when ANSI terminal is detected).

NXF_ANSI_SUMMARY

Enables/disables ANSI completion summary: true\|false (default: print summary if execution last more than 1 minute).

NXF_ASSETS

Defines the directory where downloaded pipeline repositories are stored (default: $NXF_HOME/assets)

NXF_CACHE_DIR

:::{versionadded} 24.02.0-edge :::

Defines the base cache directory when using the default cache store (default: "$launchDir/.nextflow").

NXF_CHARLIECLOUD_CACHEDIR

Directory where remote Charliecloud images are stored. When using a computing cluster it must be a shared folder accessible from all compute nodes.

NXF_CLOUDCACHE_PATH

:::{versionadded} 23.07.0-edge :::

Defines the base cache path when using the cloud cache store.

NXF_CLOUD_DRIVER

Defines the default cloud driver to be used if not specified in the config file or as command line option, either aws or google.

NXF_CONDA_CACHEDIR

Directory where Conda environments are stored. When using a computing cluster it must be a shared folder accessible from all compute nodes.

NXF_CONDA_ENABLED

:::{versionadded} 22.08.0-edge :::

Enable the use of Conda recipes defined by using the {ref}process-conda directive. (default: false).

NXF_CONTAINER_ENTRYPOINT_OVERRIDE

:::{deprecated} 22.10.0 :::

When true, override the container entrypoint with /bin/bash (default: false).

NXF_DATE_FORMAT

:::{versionadded} 25.07.0-edge :::

Defines the format for date and time representations in notifications and reports. Supports custom formats (e.g., yyyy-MM-dd HH:mm:ss) or iso for ISO 8601 format with timezone (default: dd-MMM-yyyy HH:mm:ss).

NXF_DEFAULT_DSL

:::{versionadded} 22.03.0-edge :::

Defines the DSL version that should be used in not specified otherwise in the script of config file (default: 2)

NXF_DISABLE_CHECK_LATEST

:::{versionadded} 23.09.0-edge :::

Nextflow automatically checks for a newer version of itself unless this option is enabled (default: false).

NXF_DISABLE_JOBS_CANCELLATION

:::{versionadded} 21.12.0-edge :::

Disables the cancellation of child jobs on workflow execution termination.

NXF_DISABLE_PARAMS_TYPE_DETECTION

:::{versionadded} 23.07.0-edge :::

Disables the automatic type detection of command line parameters.

NXF_DISABLE_WAVE_SERVICE

:::{versionadded} 23.08.0-edge :::

Disables the requirement for Wave service when enabling the Fusion file system.

NXF_ENABLE_AWS_SES

:::{versionadded} 23.06.0-edge :::

Enable to use of AWS SES native API for sending emails in place of legacy SMTP settings (default: false)

NXF_ENABLE_FS_SYNC

:::{versionadded} 23.10.0 :::

When enabled the job script will execute Linux sync command on job completion. This may be useful to synchronize the job state over shared file systems (default: false)

NXF_ENABLE_SECRETS

:::{versionadded} 21.09.0-edge :::

Enable Nextflow secrets features (default: true)

NXF_ENABLE_STRICT

:::{versionadded} 22.05.0-edge :::

Enable Nextflow strict execution mode (default: false)

NXF_ENABLE_VIRTUAL_THREADS

:::{versionadded} 23.05.0-edge :::

Enable the use of virtual threads in the Nextflow runtime (default: false)

NXF_EXECUTOR

Defines the default process executor, e.g. sge

NXF_FILE_ROOT

:::{versionadded} 23.05.0-edge :::

The file storage path against which relative file paths are resolved.

For example, with NXF_FILE_ROOT=/some/root/path, the use of file('hello') will be resolved to the absolute path /some/root/path/hello. A remote root path can be specified using the usual protocol prefix, e.g. NXF_FILE_ROOT=s3://my-bucket/data. Files defined using an absolute path are not affected by this setting.

NXF_FUSION_TRACE

:::{versionadded} 26.04.0 :::

When set to true, collect task resource metrics (CPU, memory, I/O) from the Fusion trace file (.fusion/trace.json) produced in the task work directory, replacing the metrics collected by the default bash command-trace wrapper. Requires Fusion to be enabled. GPU metrics from Fusion are always collected regardless of this setting. Defaults to false.

NXF_HOME

Nextflow home directory (default: $HOME/.nextflow).

NXF_JAVA_HOME

Defines the path location of the Java VM installation used to run Nextflow. This variable overrides the JAVA_HOME variable if defined.

NXF_JVM_ARGS

:::{versionadded} 21.12.1-edge :::

Allows the setting Java VM options. This is similar to NXF_OPTS however it's only applied the JVM running Nextflow and not to any java pre-launching commands.

NXF_LOG_FILE

The filename of the Nextflow log (default: .nextflow.log)

NXF_OFFLINE

When true prevents Nextflow from automatically downloading and updating remote project repositories (default: false).

:::{versionchanged} 23.09.0-edge This option also disables the automatic version check (see NXF_DISABLE_CHECK_LATEST). :::

:::{versionchanged} 23.11.0-edge This option also prevents plugins from being downloaded. Plugin versions must be specified in offline mode, or else Nextflow will fail. :::

NXF_OPTS

Provides extra options for the Java and Nextflow runtime. It must be a blank separated list of -Dkey[=value] properties.

NXF_ORG

Default organization prefix when looking for a hosted repository (default: nextflow-io).

NXF_PARAMS_FILE

:::{versionadded} 20.10.0 :::

Defines the path location of the pipeline parameters file .

NXF_PID_FILE

Name of the file where the process PID is saved when Nextflow is launched in background.

NXF_PLUGINS_ALLOWED

:::{versionadded} 25.04.0 :::

Comma separated list of plugin IDs that can be used in a workflow executions e.g. NXF_PLUGINS_ALLOWED=nf-amazon,nf-tower,nf-wave. Use empty string to disallow all plugins.

NXF_PLUGINS_DEFAULT

Whether to use the default plugins when no plugins are specified in the Nextflow configuration (default: true).

NXF_PLUGINS_DIR

The path where the plugin archives are loaded and stored (default: $NXF_HOME/plugins).

NXF_PLUGINS_REGISTRY_URL

:::{versionadded} 25.08.0-edge :::

Specifies the URL of the plugin registry used to download and resolve plugins. This allows using custom or private plugin registries instead of the default public registry.

NXF_PLUGINS_TEST_REPOSITORY

:::{versionadded} 23.04.0 :::

Defines a custom plugin registry or plugin release URL for testing plugins outside of the main registry.

NXF_PUBLISH_FAIL_ON_ERROR

:::{versionadded} 24.04.3 :::

Defines the default behavior of publishDir.failOnError setting. See {ref}publishDir<process-publishdir> directive for more information.

NXF_RETRY_POLICY_DELAY

:::{versionadded} 25.06.0-edge :::

Delay used for HTTP retryable operations (default: 350ms).

NXF_RETRY_POLICY_JITTER

:::{versionadded} 25.06.0-edge :::

Jitter value used for HTTP retryable operations (default: 0.25).

NXF_RETRY_POLICY_MAX_ATTEMPTS

:::{versionadded} 25.06.0-edge :::

Max number of attempts used for HTTP retryable operations (default: 5).

NXF_RETRY_POLICY_MAX_DELAY

:::{versionadded} 25.06.0-edge :::

Max delay used for HTTP retryable operations (default: 90s).

NXF_RETRY_POLICY_MULTIPLIER

:::{versionadded} 25.08.0-edge :::

Delay multiplier used for HTTP retryable operations (default: 2.0).

NXF_SCM_FILE

:::{versionadded} 20.10.0 :::

Defines the path location of the SCM config file .

NXF_SINGULARITY_CACHEDIR

Directory where remote Singularity images are stored. When using a computing cluster it must be a shared folder accessible from all compute nodes.

NXF_SINGULARITY_LIBRARYDIR

:::{versionadded} 21.09.0-edge :::

Directory where remote Singularity images are retrieved. It should be a directory accessible to all compute nodes.

NXF_SPACK_CACHEDIR

Directory where Spack environments are stored. When using a computing cluster it must be a shared folder accessible from all compute nodes.

NXF_SPACK_ENABLED

:::{versionadded} 23.02.0-edge :::

Enable the use of Spack recipes defined by using the {ref}process-spack directive. (default: false).

NXF_SYNTAX_PARSER

:::{versionadded} 25.02.0-edge :::

Set to 'v2' to use the {ref}strict syntax <strict-syntax-page> for Nextflow scripts and config files (default: 'v1').

NXF_TEMP

Directory where temporary files are stored

NXF_TRACE

Enable trace level logging for the specified packages. Equivalent to the -trace command-line option.

NXF_VER

Defines which version of Nextflow to use.

NXF_WORK

Directory where working files are stored (usually your scratch directory)

NXF_WRAPPER_STAGE_FILE_THRESHOLD

:::{versionadded} 23.05.0-edge :::

Enables writing large staging scripts to a separate .command.stage file. The value defines the minimum size of the .command.run staging script for it to be written to the separate file (default when enabled: '1 MB').

This setting is useful for executors that impose a size limit on job scripts.

Seqera Platform settings

TOWER_ACCESS_TOKEN

Specifies the access token for authenticating with Seqera Platform. Can also be configured using the tower.accessToken config option.

TOWER_API_ENDPOINT

Specifies the Seqera Platform API endpoint (default: https://api.cloud.seqera.io). Can also be configured using the tower.endpoint config option.

TOWER_AUTH_DOMAIN

:::{versionadded} 25.10.0 :::

Specifies the Auth0 domain for authenticating with Seqera Platform when connecting to a custom endpoint. When specified, this value takes precedence over the built-in mappings for known Seqera endpoints. Must be used in conjunction with TOWER_AUTH_CLIENT_ID.

TOWER_AUTH_CLIENT_ID

:::{versionadded} 25.10.0 :::

Specifies the Auth0 client ID for authenticating with a custom Seqera Platform endpoint. Must be used in conjunction with TOWER_AUTH_DOMAIN.

TOWER_REFRESH_TOKEN

Specifies the refresh token for maintaining authentication with Seqera Platform. Can also be configured using the tower.refreshToken config option.

TOWER_COMPUTE_ENV_ID

Specifies the Seqera Platform compute environment ID. When specified, the scheduler resolves the compute environment directly by this ID instead of inferring a suitable compute environment. Can also be configured using the tower.computeEnvId config option.

TOWER_WORKSPACE_ID

Specifies the Seqera Platform workspace ID. Can also be configured using the tower.workspaceId config option.

Other settings

FTP_PROXY

:::{versionadded} 21.06.0-edge :::

Defines the FTP proxy server. Proxy authentication is supported by providing the credentials in the proxy URL, e.g. ftp://user:password@proxy-host.com:port.

HTTP_PROXY

Defines the HTTP proxy server.

:::{versionadded} 21.06.0-edge Proxy authentication is supported by providing the credentials in the proxy URL, e.g. http://user:password@proxy-host.com:port. :::

HTTPS_PROXY

Defines the HTTPS proxy server.

:::{versionadded} 21.06.0-edge Proxy authentication is supported by providing the credentials in the proxy URL, e.g. https://user:password@proxy-host.com:port. :::

NO_COLOR

Disables ANSI color codes in Nextflow log output. When this variable is set, Nextflow prints plain text logs following the NO_COLOR standard.

If both NO_COLOR and NXF_ANSI_LOG are set, NXF_ANSI_LOG takes precedence.

NO_PROXY

Defines one or more host names that should not use the proxy server. Separate multiple names using a comma character.

TERMINAL_WIDTH

Forces the terminal width of ANSI-formatted log output. Overrides automatic terminal width detection and uses the specified width for line wrapping when set to an integer value.