WSL Setup for PDAC GWAS Tutorial

Running the PDAC GWAS Tutorial on Windows (via WSL)

For Windows users: Using Windows Subsystem for Linux (WSL) is strongly recommended for this tutorial. The pipeline uses bash scripts and Linux/macOS command-line tools, which work most consistently inside WSL.

Why WSL?

Aspect	Windows CMD/PowerShell	WSL (Linux)
Tool setup	Requires separate Windows binaries and PATH edits	Tutorial scripts install tools into the project folder
Bash scripts	PowerShell emulation (fragile)	Full bash compatibility
File paths	Windows-style (backslashes, drive letters)	Unix-style (forward slashes)
Performance	Slower for file I/O intensive tasks	Native Linux speed
Scripting	Complex escaping, quoting issues	Standard shell behavior

Recommendation: Install WSL2 with Ubuntu, then follow this guide.

---

Prerequisites

1. Enable WSL2 on Windows

Open PowerShell as Administrator and run:

wsl --install
# or, if you already have WSL1:
wsl --set-default-version 2

Restart your computer, then verify:

wsl --list --verbose

You should see Ubuntu (or your chosen distro) with VERSION = 2.

2. Install Ubuntu in WSL

wsl --install -d Ubuntu

Or use the Microsoft Store to download Ubuntu 22.04 LTS or later.

3. Launch WSL Terminal

From PowerShell or Windows Terminal:

wsl

Or click Ubuntu in Windows Terminal tabs.

The short video below shows how to open Ubuntu from Windows Terminal:

Basic WSL Preparation

Once you’re in the WSL terminal, run these commands once to prepare Ubuntu. These commands install only the basic utilities needed to download and run the tutorial setup scripts. R, PLINK2, PLINK1.9, METAL, micromamba, and REGENIE are checked or installed later by bash scripts/dev/tools_setup.sh.

Step 1: Update Package Manager

sudo apt-get update -y
sudo apt-get upgrade -y

Note: The sudo prompt may ask for your password (the one you set during WSL Ubuntu installation).

Step 2: Install Basic Utilities

sudo apt-get install -y curl wget git unzip tar bzip2

Verify the basic utilities:

git --version
curl --version
wget --version

R is checked during Step 5 of the main tutorial. If it is missing, bash scripts/dev/tools_setup.sh will try to install it.

---

Accessing Your Files

Windows Path → WSL Path Mapping

Windows	WSL
C:\Users\...	/home/username/...
C:\ drive	/mnt/c/
S:\ drive	/mnt/s/
D:\ drive	/mnt/d/

Example: Accessing S: Drive and Example folder

Your repo at S:\Example is accessible in WSL as:

cd /mnt/s/Example
ls -la

You can return back to your HOME directory with:

cd $HOME
ls -la

Troubleshooting

Issue: WSL cannot connect to the internet on a managed network

Reason: Some universities, hospitals, and institutes use a network proxy. Windows may already know this proxy, but WSL may not use the Windows setting automatically.

Ask your local IT team for the proxy address and port. It usually looks like:

http://proxy.example.org:3128/

Replace the example proxy below with your institution’s real proxy:

PROXY="http://proxy.example.org:3128/"
NO_PROXY="localhost,127.0.0.1"

Set the proxy for the current WSL terminal:

export http_proxy="$PROXY"
export https_proxy="$PROXY"
export ftp_proxy="$PROXY"
export HTTP_PROXY="$PROXY"
export HTTPS_PROXY="$PROXY"
export FTP_PROXY="$PROXY"
export no_proxy="$NO_PROXY"
export NO_PROXY="$NO_PROXY"

Test the connection:

curl -I https://github.com
wget --spider https://github.com

If this works, make it permanent for future WSL terminals:

cat >> "$HOME/.bashrc" <<'EOF'

# Proxy for WSL network access.
# Replace this example with your institution's proxy.
export http_proxy="http://proxy.example.org:3128/"
export https_proxy="http://proxy.example.org:3128/"
export ftp_proxy="http://proxy.example.org:3128/"
export HTTP_PROXY="http://proxy.example.org:3128/"
export HTTPS_PROXY="http://proxy.example.org:3128/"
export FTP_PROXY="http://proxy.example.org:3128/"
export no_proxy="localhost,127.0.0.1"
export NO_PROXY="localhost,127.0.0.1"
EOF

source "$HOME/.bashrc"

apt-get may need its own proxy setting because it runs with sudo:

sudo tee /etc/apt/apt.conf.d/95proxy >/dev/null <<EOF
Acquire::http::Proxy "$PROXY";
Acquire::https::Proxy "$PROXY";
Acquire::ftp::Proxy "$PROXY";
EOF

sudo apt-get update

Git can also be configured separately:

git config --global http.proxy "$PROXY"
git config --global https.proxy "$PROXY"
git ls-remote https://github.com/git/git.git HEAD

If your proxy requires a username or password, ask your IT team for the recommended WSL setup. Avoid putting passwords into shared scripts or tutorial files.

Issue: “File not found” when accessing Windows files

Solution: Use /mnt/ prefix for Windows drives:

# ✗ Wrong
cd S:\Github\how-to-gwas-pdac

# ✓ Correct
cd /mnt/s/Github/how-to-gwas-pdac

Issue: Slow performance on /mnt/s/ (Windows drive)

Reason: WSL filesystem performance is slower when accessing Windows drives.

Solution: Clone the repo inside WSL:

git clone https://github.com/mgentiluomo/how-to-gwas-pdac.git ~/how-to-gwas-pdac
cd ~/how-to-gwas-pdac

---

Quick Reference: WSL Commands

# Check WSL version and distro
wsl --list --verbose

# Switch default distro
wsl --set-default <distro-name>

# Enter WSL
wsl

# Exit WSL
exit

# Run single WSL command from PowerShell
wsl bash -c "cd /mnt/s/Github/how-to-gwas-pdac && ls"

# Update WSL
wsl --update

---

Next Steps

1. Follow Before you start: setup and your first QC pipeline
2. Return to this page if you need help with WSL paths or basic WSL commands.

Good luck!