TutorialsWorkflowsOpen dataDownloadsOur Team
How Tos
Nextflow in Windows with WSL2
Sarah Griffiths
Sarah Griffiths
October 20, 2021
2 min

It is easy to run and develop Nextflow workflows on Windows but there are some additional set up steps required. We have found the set up can be tricky so have outlined the steps required here with links to trouble shooting and further help.

You will need Windows 10 and it is critical that you have Admin privileges for all the steps,

  1. Check your windows version is sufficient.
  • Start > search ‘Windows update settings’ > at the bottom select ‘OS Build info’

Under Windows specifications - Under OS Build info - Your Build number must be 18362.1049 or 18363.1049 (or higher).

  • Make any Windows updates that are required, this will cause your computer to restart and could take a while.
  1. Enable Windows Subsystem for Linux (WSL)

If you have Windows 10 May 2020 (2004) update (or later) installed you can install WSL with a single command.

  • Start > search for ‘powershell’ > Right click and run as admin > copy/paste the following -
wsl.exe --install
  • Restart your computer and you will be prompted to set up Ubuntu with a username and password and can skip to step 8.

If you have an earlier Windows version or the above has not worked continue following the steps -

  • Start > search for ‘powershell’ > Right click and run as admin > copy/past the following -
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart 
  1. Enable virtual machine platform
  • Copy and paste the following in to Powershell
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart 
  1. Update to WSL2
  • Download this WSL2 update file and run through the installation wizard: https://wslstorestorage.blob.core.windows.net/wslblob/wsl_update_x64.msi

You can find a WSL installation troubleshooting guide here

  1. Set WSL2 as the default version.
  • Open a new Powershell with admin rights
  • In Powershell copy and paste
wsl --set-default-version 2
  1. Download Ubuntu
  • From the start menu open the Microsoft store
  • In Search bar type Ubuntu
  • Download and install one of the ubuntu 64-bit versions either: Hirsute 21.04, Groovy 20.10, Focal 20.04 (LTS), Bionic 18.04 (LTS).
  1. Now you have WSL and Ubuntu installed check which WSL version is being used with which linux system with
  • Type -
wsl --list –v


H:\> wsl --list -v
  NAME                   STATE           VERSION
* Ubuntu                 Running         2
  docker-desktop-data    Running         2
  docker-desktop         Running         2
  Ubuntu-18.04           Running         1

  • Change WSL version with
wsl --set-version <distribution name> <version>


H:\> wsl --set-version Ubuntu 2
Conversion in progress, this may take a few minutes...
Conversion complete.
  1. Set up Docker
  • If you don’t already have it download Docker Desktop.
  • Right click the downloaded file and select Run the installation as an administrator and follow the install wizard.
  • If user is not the administrator, the user will need to be added before docker will work.
  • To add a new user - in Powershell type

# To find out your username (in case you are unsure) type 

# Add that user to docker with the commands

sudo groupadd docker
sudo usermod -aG docker <username>
  • Once the user is added you will need to reboot your PC
  1. Enable WSL2 in docker

These docker instructions can also be found here

  • Start Docker Desktop from the Windows Start menu.
  • From the Docker menu, select Settings > General
  • The ‘Use the WSL 2 based engine’ box should already be ticked, if not tick the box and click Apply & Restart.

Docker settings
Docker settings

  • Next Go to Settings > Resources > WSL Integration
  • ‘Enable integration with my default WSL distro’ should be ticked and select Enable integration with the Ubuntu version you have just downloaded.

Docker WSL Integration
Docker WSL Integration

  • If you are unsure of the Ubuntu version go to Powershell and type


H:\> wsl 
H:\> lsb_release -d 
Description:    Ubuntu 20.04.3 LTS
  1. Install Java
  • Install java version 8+ (but < 15) by typing -
sudo apt install openjdk-11-jre-headless
  1. Now download and install Nextflow
curl -s https://get.nextflow.io | bash
chmod +x nextflow
  • Make sure Nextflow is updated to the latest version by typing -
./nextflow self-update 
  1. Test nextflow

Now try the template workflow

Nextflow will automatically pull the docker image and build the container. If you already have data to use with a workflow you can skip the git clone repository step.


# Clone the repository just to aquire some demo data (skip if you have data)
git clone https://github.com/epi2me-labs/wf-template.git

# run the workflow to see required parameters
./nextflow run epi2me-labs/wf-template

# run the workflow with the required parameters


./nextflow run epi2me-labs/wf-template     -w ${OUTPUT}/workspace     -profile standard     --fastq wf-template/test_data     --out_dir wf-template/${OUTPUT}

There is a guide from Nextflow which goes in to greater detail and has additional steps useful for developing workflows.

If you had any problems with this tutorial or think any additional information would be useful then please let us know so we can improve it for other users.



Related Posts

Changing Location of Workflow Container Images
October 20, 2021
2 min
© 2020 - 2022
Oxford Nanopore Technologies
All Rights Reserved.

Quick Links

TutorialsWorkflowsOpen DataContact

Social Media