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.
Nextflow settings
NXF_AGENT_API_KEY
The credential used to authenticate with the model provider of an agent. Overridden by the agent.apiKey configuration setting, and takes precedence over the API provider's own variable (OPENAI_API_KEY, ANTHROPIC_API_KEY, and the others listed under Other settings). Unlike those it is provider-neutral: it applies to any model provider, and it is presented to whatever endpoint the agent targets — including one Nextflow cannot attribute to a provider, such as a gateway.
NXF_AGENT_BASE_URL
The base URL of the endpoint that serves an agent model, e.g. http://localhost:8000/v1. Overridden by the agent.baseUrl configuration setting, and takes precedence over the API provider's own variable (OPENAI_BASE_URL, ANTHROPIC_BASE_URL, AZURE_OPENAI_ENDPOINT). Unlike those it applies to any model provider. When unset, the model provider's default endpoint is used.
This value is part of an agent's cache key, so changing it re-runs the agent instead of resuming it. NXF_AGENT_API_KEY is not part of the cache key.
NXF_AGENT_MODE
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.
Nextflow also enables agent mode automatically when AGENT or CLAUDECODE is set to a truthy value. NXF_AGENT_MODE overrides that detection in either direction. Set NXF_AGENT_MODE=false to restore the ANSI log when a human watches a run in an agent-created environment, such as a detached tmux session.
This setting is unrelated to the other NXF_AGENT_* variables. It controls how Nextflow formats its own console output for an external AI agent, and has no connection to the agent script definition.
NXF_AGENT_RPC_REMOTE_HOST
Host name a containerized agent task uses to reach the driver's agent RPC broker, for deployments where that address belongs to the environment rather than to the pipeline. Equivalent to agent.rpc.remoteHost, which takes precedence when both are set. These are the first two rungs of a ladder that continues into inference: with neither set, Nextflow derives the address from the executor, the container engine and the driver host, and rejects the configurations no address can serve before the run starts. See Agents.
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
Defines the base cache directory when using the default cache store (default: "$launchDir/.nextflow").
This must be a local directory. To store the task cache in object storage, use NXF_CLOUDCACHE_PATH.
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
Defines the base cache path when using the cloud cache store. See Cache stores for more information.
NXF_CLOUDINFO_ENABLED
When true, use the Seqera Cloud Info service to select the machine type for Google Batch tasks (default: true).
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
Enable the use of Conda recipes defined by using the conda directive. (default: false).
NXF_CONTAINER_ENTRYPOINT_OVERRIDE
When true, override the container entrypoint with /bin/bash (default: false).
NXF_DATE_FORMAT
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
Defines the DSL version that should be used in not specified otherwise in the script of config file (default: 2)
NXF_DISABLE_CHECK_LATEST
Nextflow automatically checks for a newer version of itself unless this option is enabled (default: false).
NXF_DISABLE_JOBS_CANCELLATION
Disables the cancellation of child jobs on workflow execution termination.
NXF_DISABLE_PARAMS_TYPE_DETECTION
Disables the automatic type detection of command line parameters.
NXF_DISABLE_WAVE_SERVICE
Disables the requirement for Wave service when enabling the Fusion file system.
NXF_ENABLE_AWS_SES
Enable to use of AWS SES native API for sending emails in place of legacy SMTP settings (default: false)
NXF_ENABLE_FS_SYNC
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
Enable Nextflow secrets features (default: true)
NXF_ENABLE_STRICT
Enable Nextflow strict execution mode (default: false)
NXF_ENABLE_VIRTUAL_THREADS
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
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
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 (default: false).
NXF_HOME
Nextflow home directory (default: $HOME/.nextflow).
NXF_HTTPCLIENT_CONNECT_TIMEOUT
Maximum time to wait for a connection to the Git hosting service API, such as GitHub or GitLab, for a single attempt (default: 60s). Must be greater than zero.
Nextflow retries connection attempts that time out, because the request never reached the server. An unreachable host fails after this timeout multiplied by NXF_RETRY_POLICY_MAX_ATTEMPTS, about 5 minutes with the default settings. Set a lower value, such as 5s, to cap the worst case at about 30 seconds. The NXF_RETRY_POLICY_* variables configure the retry behavior.
NXF_HTTPCLIENT_REQUEST_TIMEOUT
Maximum time to wait for a response from the Git hosting service API after the connection is established, for a single attempt (default: 60s). Set to 0s to wait indefinitely.
Nextflow does not retry requests that time out waiting for a response, because the request reached the server and the server may already have processed it.
NXF_IGNORE_RESUME_HISTORY
Disables the history file (.nextflow/history) used to track previous runs (default: false).
When the history file is disabled, nextflow run requires an explicit run name (-name), and -resume requires an explicit session ID. See Cache stores for more information.
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
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).
This option also disables the automatic version check (see NXF_DISABLE_CHECK_LATEST).
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
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
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
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
Defines a custom plugin registry or plugin release URL for testing plugins outside of the main registry.
NXF_PUBLISH_FAIL_ON_ERROR
Defines the default behavior of publishDir.failOnError setting. See publishDir directive for more information.
NXF_RETRY_POLICY_DELAY
Delay used for HTTP retryable operations (default: 350ms).
NXF_RETRY_POLICY_JITTER
Jitter value used for HTTP retryable operations (default: 0.25).
NXF_RETRY_POLICY_MAX_ATTEMPTS
Max number of attempts used for HTTP retryable operations (default: 5).
NXF_RETRY_POLICY_MAX_DELAY
Max delay used for HTTP retryable operations (default: 90s).
NXF_RETRY_POLICY_MULTIPLIER
Delay multiplier used for HTTP retryable operations (default: 2.0).
NXF_SCM_FILE
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.
The NXF_SINGULARITY_CACHEDIR variable is not applied when a container image is specified using an oras:// URI. In that case, the image reference is passed directly to Singularity, independently of Nextflow's caching mechanism.
NXF_SINGULARITY_LIBRARYDIR
Directory where remote Singularity images are retrieved. It should be a directory accessible to all compute nodes.
The NXF_SINGULARITY_LIBRARYDIR variable is not applied when a container image is specified using an oras:// URI. In that case, the image reference is passed directly to Singularity, independently of Nextflow's caching mechanism.
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
Enable the use of Spack recipes defined by using the spack directive. (default: false).
NXF_SYNTAX_PARSER
The strict parser is disabled by default.
The strict parser is enabled by default.
Set to 'v2' to use the strict syntax parser for Nextflow code. Set to 'v1' to fall back to the legacy parser.
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
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
The access token for authenticating with Seqera Platform. Can also be configured using the tower.accessToken config option.
TOWER_API_ENDPOINT
The Seqera Platform API endpoint (default: https://api.cloud.seqera.io). Can also be configured using the tower.endpoint config option.
TOWER_AUTH_DOMAIN
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
The Auth0 client ID for authenticating with a custom Seqera Platform endpoint. Must be used in conjunction with TOWER_AUTH_DOMAIN.
TOWER_REFRESH_TOKEN
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
The Seqera Platform workspace ID. Can also be configured using the tower.workspaceId config option.
Other settings
ALL_PROXY
Defines a proxy server used as a fallback for any protocol (HTTP, HTTPS, FTP) that does not have a scheme-specific proxy variable set. A scheme-specific variable (e.g. HTTPS_PROXY) takes precedence over ALL_PROXY. Proxy authentication is supported by providing the credentials in the proxy URL.
ANTHROPIC_API_KEY
The credential used to authenticate with the model provider of an agent whose API provider is anthropic. Used only when neither the agent.apiKey configuration setting nor NXF_AGENT_API_KEY is set, and only when the endpoint the agent resolved belongs to Anthropic — being an Anthropic credential, it is never presented elsewhere.
ANTHROPIC_BASE_URL
The base URL of the endpoint that serves an agent model whose API provider is anthropic. Used only when neither the agent.baseUrl configuration setting nor NXF_AGENT_BASE_URL is set.
AZURE_OPENAI_API_KEY
The credential used to authenticate with the model provider of an agent whose API provider is azure. Used under the same conditions as ANTHROPIC_API_KEY. The langchain4j runner cannot reach Azure OpenAI — its URL shape and api-version handling need a client it does not ship — so this applies to a runner that can.
AZURE_OPENAI_ENDPOINT
The endpoint that serves an agent model whose API provider is azure — Azure's spelling of <PROVIDER>_BASE_URL. Used only when neither the agent.baseUrl configuration setting nor NXF_AGENT_BASE_URL is set.
COLUMNS
Sets the terminal width of ANSI-formatted log output when TERMINAL_WIDTH is not set to a positive integer.
Bash sets COLUMNS in interactive shells but does not export it, so it is not visible to Nextflow unless you export it explicitly, e.g. export COLUMNS=100, or set it for the command, e.g. COLUMNS=100 nextflow run <pipeline>. In non-interactive contexts such as a batch job script, COLUMNS is not set at all — use TERMINAL_WIDTH to force a width there.
FTP_PROXY
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. Credentials containing special characters must be URL-encoded (percent-encoded).
GEMINI_API_KEY
The credential used to authenticate with the model provider of an agent whose API provider is gemini, or google when GOOGLE_API_KEY is unset. Used under the same conditions as ANTHROPIC_API_KEY.
GOOGLE_API_KEY
The credential used to authenticate with the model provider of an agent whose API provider is google, or gemini when GEMINI_API_KEY is unset. Used under the same conditions as ANTHROPIC_API_KEY.
HTTP_PROXY
Defines the HTTP proxy server. Proxy authentication is supported by providing the credentials in the proxy URL, e.g. http://user:password@proxy-host.com:port. Credentials containing special characters must be URL-encoded (percent-encoded).
HTTPS_PROXY
Defines the HTTPS proxy server. Proxy authentication is supported by providing the credentials in the proxy URL, e.g. https://user:password@proxy-host.com:port. Credentials containing special characters must be URL-encoded (percent-encoded).
When connecting to HTTPS targets through an authenticating proxy, the JDK strips proxy credentials from the CONNECT request for the schemes listed in jdk.http.auth.tunneling.disabledSchemes (default Basic), which can cause a 407 error. Nextflow clears this property automatically when the proxy URL carries credentials. If you set the property yourself, Nextflow does not override it — clear it explicitly to allow Basic proxy authentication over HTTPS with NXF_OPTS='-Djdk.http.auth.tunneling.disabledSchemes='.
MISTRAL_API_KEY
The credential used to authenticate with the model provider of an agent whose API provider is mistral. Used under the same conditions as ANTHROPIC_API_KEY.
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.
OPENAI_API_KEY
The credential used to authenticate with the model provider of an agent whose API provider is openai. Used only when neither the agent.apiKey configuration setting nor NXF_AGENT_API_KEY is set, and only when the endpoint the agent resolved belongs to OpenAI — being an OpenAI credential, it is never presented to another provider or to an unattributed endpoint such as a gateway. Set agent.apiProvider = 'openai' to declare that a gateway accepts it.
OPENAI_BASE_URL
The base URL of the OpenAI-compatible endpoint that serves an agent model whose API provider is openai. Used only when neither the agent.baseUrl configuration setting nor NXF_AGENT_BASE_URL is set.
OPENROUTER_API_KEY
The credential used to authenticate with the model provider of an agent whose API provider is openrouter — which includes an openai/ model pointed at https://openrouter.ai/…, since the model prefix names the wire protocol and the endpoint names the credential namespace. Used under the same conditions as ANTHROPIC_API_KEY.
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 a positive integer. Values that are not positive integers are ignored, in which case Nextflow falls back to COLUMNS and then to automatic detection.