nextflow run
Execute a pipeline.
Usage
$ nextflow run [options] [project]
Description
The run command runs a local pipeline script or a remote pipeline project.
Options
-E
Export all current system environment variables.
-ansi-log
Enable or disable ANSI console logging.
-bucket-dir
Remote bucket where intermediate result files are stored. When running a hybrid workflow, -bucket-dir and -work-dir should define separate work directories for remote tasks and local tasks, respectively.
-cache
Enable or disable process caching.
-d, -deep
Ignored for new multi-revision asset management strategy. Still used in legacy assets.
Create a shallow clone of the specified depth.
-disable-jobs-cancellation
Do not cancel child jobs when the run terminates.
-dump-channels
Dump channels for debugging. Optionally accepts a comma-separated list of channel tags to select which channels are printed.
-dump-hashes
Dump task hash keys for debugging purposes.
You can use -dump-hashes json to dump the task hash keys as JSON for easier post-processing. See the caching and resuming tips for more details.
-e.<key>=<value>
Add the specified variable to the execution environment.
-entry
Use params in the entry workflow to call different workflows from the command line.
Entry workflow to run.
-h, -help
Print the command usage.
-hub (github)
Service hub where the project is hosted. Options: gitlab or bitbucket.
-latest
Pull the latest changes before the run.
-lib
Library extension path.
-main-script (main.nf)
The script file to execute when launching a project directory or repository. Should be a path relative to the project root. For example, -main-script subproject/main.nf.
The project nextflow.config is always read from the project root regardless of the main script location.
-name
Assign a mnemonic name to the pipeline run.
-offline
Do not check for remote project updates.
-o, -output-dir (results)
Directory where workflow outputs are stored.
-output-format
Output format for printing workflow outputs. Options: text (default), json, none.
-params-file
Load script parameters from a JSON/YAML file.
-plugins
Comma-separated list of plugin ids to apply to the pipeline run.
-preview
Run the workflow script without running any processes.
-profile
Choose a configuration profile.
-qs, -queue-size
Maximum number of processes each executor can run in parallel.
-resume
Run the script using cached results. Use this to continue a run that stopped because of an error.
-r, -revision
Project revision to run. Can be a git branch, tag, or commit SHA number.
When passing a git tag or branch, the workflow.revision and workflow.commitId fields are populated. When passing only the commit hash, workflow.revision is not defined.
-stub-run, -stub
Run the workflow, replacing process scripts with command stubs.
-test
Test the script function with the specified name.
-user
Private repository user name.
-with-apptainer
Enable process execution in an Apptainer container.
-with-charliecloud
Enable process execution in a Charliecloud container.
-with-agent-trace
Log a readable trace of each agent's execution — its turns, the model reasoning and the tool invocations — at INFO level; tool inputs and outputs are logged at DEBUG. Equivalent to the agent.trace configuration setting.
-with-cloudcache
Store cache metadata in an object storage bucket with the Cloud cache plugin.
-with-conda
Use the specified Conda environment package or file, which must end with .yml or .yaml.
-with-dag (dag-<timestamp>.html)
Create pipeline DAG file.
The default format was changed from dot to html.
-with-docker
Enable process execution in a Docker container.
-N, -with-notification
Send a notification email on workflow completion to the specified recipients.
-with-podman
Enable process execution in a Podman container.
-with-report (report-<timestamp>.html)
Create workflow execution HTML report.
-with-singularity
Enable process execution in a Singularity container.
-with-spack
Use the specified Spack environment package or file, which must end with .yaml.
-with-timeline (timeline-<timestamp>.html)
Create workflow execution timeline.
-with-tower (https://api.cloud.seqera.io)
Monitor workflow execution with Seqera Platform (formerly Tower Cloud).
-with-trace (trace-<timestamp>.txt)
Create workflow execution trace file.
-with-wave (https://wave.seqera.io)
Use Wave containers.
-with-weblog (http://localhost)
This option is no longer supported. Use the nf-weblog plugin explicitly instead.
Send workflow status messages to the target URL over HTTP.
-w, -work-dir (work)
Directory where intermediate result files are stored.
Examples
Run a specific revision of a remote pipeline:
$ nextflow run nextflow-io/hello -r v1.1
N E X T F L O W ~ version 20.07.1
Launching `nextflow-io/hello` [grave_cajal] - revision: 1c3e9e7404 [v1.1]
Choose a profile for running the project. This example assumes a profile named docker is defined in the config file:
$ nextflow run main.nf -profile docker
Run a pipeline and generate the summary HTML report. See Reports for more information about the metrics:
$ nextflow run main.nf -with-report
Run a pipeline with a custom queue size. By default, the queue size is the number of available CPUs:
$ nextflow run nextflow-io/hello -qs 4
Run the pipeline with a specific workflow as the entry point:
$ nextflow run main.nf -entry workflow_A
Run a pipeline with monitoring in Seqera Platform:
$ nextflow run nextflow-io/hello -with-tower
Run a pipeline with a custom parameters file in YAML or JSON:
$ nextflow run main.nf -params-file pipeline_params.yml
See Pipeline parameters for more information about writing custom parameters files.