Installation

nf-core tools is a Python package that provides command-line utilities for working with nf-core pipelines. While optional, it offers helpful features for downloading, launching, and developing pipelines.

The nf-core tools package provides commands for:

• Listing available nf-core pipelines and components
• Downloading pipelines for offline use
• Launching pipelines with customized parameters
• Creating and developing new pipelines and components
• Linting and validating pipeline code

Installing nf-core tools

nf-core tools can be installed using Conda, pip, or Docker. Choose the method that best fits your environment.

Install with Conda

Conda is the recommended installation method as it handles all dependencies automatically.

To install nf-core tools with Conda:

1. Install nf-core tools in your current environment:

   conda install nf-core

2. Verify the installation:

   nf-core --version

Alternatively, create a dedicated environment with both nf-core tools and Nextflow:

1. Create a new environment:

   conda create --name nf-core-env nf-core nextflow

2. Activate the environment:

   conda activate nf-core-env

3. Verify the installation:

   nf-core --version
   nextflow -version

Install with pip

To install nf-core tools with pip:

1. Install the package:

   pip install nf-core

2. Verify the installation:

   nf-core --version

Install with Docker

To use nf-core tools with Docker:

1. Pull the nfcore/tools Docker image:

   docker pull nfcore/tools

2. Run nf-core tools commands using Docker:

   docker run -itv `pwd`:`pwd` -w `pwd` -u $(id -u):$(id -g) nfcore/tools --help

   • -i and -t are needed for the interactive CLI prompts to work (this tells Docker to use a pseudo-tty with stdin attached)
   • The -v argument tells Docker to bind your current working directory (pwd) to the same path inside the container, so that files created there will be saved to your local file system outside of the container
   • -w sets the working directory in the container to this path, so that it’s the same as your working directory outside of the container
   • -u sets your local user account as the user inside the container, so that any files created have the correct ownership permissions

3. (Optional) Create an alias to simplify commands:

   1. Add an alias in your ~/.bashrc or ~/.zshrc:

      alias nf-core="docker run -itv \`pwd\`:\`pwd\` -w \`pwd\` -u $(id -u):$(id -g) nfcore/tools"

   2. Run nf-core directly:

      nf-core --help

Docker version tags

You can use Docker image tags to specify the version you would like to use. For example, nfcore/tools:dev for the latest development version of the code, or nfcore/tools:1.14 for version 1.14 of tools. If you omit this, it will default to :latest, which should be the latest stable release.

If you need a specific version of Nextflow inside the container, you can build an image yourself. Clone the repo locally and check out whatever version of nf-core/tools that you need. Then build using the --build-arg NXF_VER flag:

docker build -t nfcore/tools:dev . --build-arg NXF_VER=20.04.0

Updating nf-core tools

To keep nf-core tools up to date with the latest features and bug fixes, update regularly using your installation method.

Update Conda install

To update your nf-core tools Conda install, run:

conda update nf-core

Update pip install

To update your nf-core tools pip install, run:

pip install --upgrade nf-core

Update Docker install

To update nf-core tools Docker image, run:

docker pull nfcore/tools

Development version

If you would like to use the latest development version of tools, install directly from the GitHub repository:

pip install --upgrade --force-reinstall git+https://github.com/nf-core/tools.git@dev

If you intend to make edits to the code, first make a fork of the repository and then clone it locally. Go to the cloned directory and install with pip (this also installs development requirements):

pip install --upgrade -r requirements-dev.txt -e .

Advanced usage

Using a specific Python interpreter

You can run nf-core tools with a specific Python interpreter. The command line usage and flags are exactly the same as if you ran with the nf-core command. Note that the module is nf_core with an underscore, not a hyphen like the console command.

For example:

python -m nf_core --help
python3 -m nf_core list
~/my_env/bin/python -m nf_core create --name mypipeline --description "This is a new skeleton pipeline"

Using with your own Python scripts

The nf-core tools functionality can be imported into your own Python scripts. For example, to get a list of all available nf-core pipelines:

import nf_core.list
wfs = nf_core.list.Workflows()
wfs.get_remote_workflows()
for wf in wfs.remote_workflows:
    print(wf.full_name)

For detailed function documentation, see the nf-core tools API reference.

Automatic version check

nf-core tools automatically checks for new versions when run. If you would prefer to skip this check, set the NFCORE_NO_VERSION_CHECK environment variable:

export NFCORE_NO_VERSION_CHECK=1

Shell completions

Auto-completion for the nf-core command is available for bash, zsh, and fish. To activate it, add the following lines to the respective shell config files:

After restarting your shell session, you should have auto-completion for the nf-core command and all its sub-commands and options.