# SD.Next with WSL on Windows

## WSL: Windows Subsystem for Linux

WSL lets you run Linux inside Windows, so you can use a full Linux environment without a separate Linux installation.

This guide covers installing a WSL2 distro on Windows 10/11 and configuring it for SD.Next.  
It targets nVidia GPUs, where WSL support is available out of the box. Other GPU vendors may work, but are not covered here.

It assumes WSL prerequisites are already enabled in Windows and that your GPU drivers are up to date.  

## WSL Installation

### Verify WSL

> [!IMPORTANT]
> WSL requires virtualization to be enabled in BIOS  
> Note that this is not compatible with some overclocking tools such as Intel's XTU  

Make sure the WSL subsystem is installed. From *Command Prompt*:  
> wsl --status  
> wsl --version

    Default Version: 2
    WSL version: 2.2.1.0
    Kernel version: 5.15.150.1-2
    WSLg version: 1.0.60
    MSRDC version: 1.2.5105
    Direct3D version: 1.611.1-81528511
    DXCore version: 10.0.25131.1002-220531-1700.rs-onecore-base2-hyp
    Windows version: 10.0.22635.3430

### Install WSL

Choose a Linux distro:

> wsl --list --online

    NAME                            FRIENDLY NAME
    AlmaLinux-8                     AlmaLinux OS 8
    AlmaLinux-9                     AlmaLinux OS 9
    AlmaLinux-Kitten-10             AlmaLinux OS Kitten 10
    Debian                          Debian GNU/Linux
    FedoraLinux-42                  Fedora Linux 42
    SUSE-Linux-Enterprise-15-SP5    SUSE Linux Enterprise 15 SP5
    SUSE-Linux-Enterprise-15-SP6    SUSE Linux Enterprise 15 SP6
    Ubuntu                          Ubuntu
    Ubuntu-24.04                    Ubuntu 24.04 LTS
    archlinux                       Arch Linux
    kali-linux                      Kali Linux Rolling
    openSUSE-Tumbleweed             openSUSE Tumbleweed
    openSUSE-Leap-15.6              openSUSE Leap 15.6
    Ubuntu-18.04                    Ubuntu 18.04 LTS
    Ubuntu-20.04                    Ubuntu 20.04 LTS
    Ubuntu-22.04                    Ubuntu 22.04 LTS
    OracleLinux_7_9                 Oracle Linux 7.9
    OracleLinux_8_7                 Oracle Linux 8.7
    OracleLinux_9_1                 Oracle Linux 9.1

Recommended: **Ubuntu-24.04 LTS**.  
Install it:

> wsl --install -d Ubuntu-24.04

    Installing: Ubuntu 24.04 LTS

When prompted, create a user and password (this guide uses `myuser`).  
After installation completes, WSL opens a `bash` shell in the new distro.  

*Note*: WSL install does not let you choose the distro friendly name or storage location. You can change those later.  

### Update WSL

From *bash*:  
> sudo apt update  
> sudo apt dist-upgrade  

**Ubuntu 24.04** already includes Python and Git, but you still need venv tools:

> sudo apt install python3.11-venv python3-pip  
> python3 --version  
> git --version  

    Python 3.11.12
    git version 2.43.0

Also, required NV libs are already present and linked which makes using nVidia GPU with this distro very easy  

### Memory

By default WSL allocates 50% of total memory on Windows  
If you want WSL to use more memory, increase its memory limit.  

For example, edit WSL configuration
> `C:\Users\<username>\.wslconfig`

    [wsl2]
    swap=0
    nestedVirtualization=false
    debugConsole=false
    memory=51539607552

This allocates 48 GB ($48 \times 1024^3$) to WSL.

> [!WARNING]
> Keep in mind that WSL allocated memory should be  
> total available memory - reserved memory required for Windows,  
> so don't go overboard  

### Move WSL

This step is *optional* if you want to move a WSL2 distro to another location.  
Default installation path is `%USERPROFILE%\AppData\Local\Packages\<PackageName_with_ID>\LocalState\ext4.vhdx`  
For example: `C:\Users\mandiv\AppData\Local\Packages\CanonicalGroupLimited.Ubuntu24.04LTS_79rhkp1fndgsc\LocalState\ext4.vhdx`  

In this example, move it to `D:\WSL\` and use the friendly name `MyUbuntu`.  

From command prompt:  
Shutdown WSL
> wsl --shutdown  
> wsl --list --verbose  

    Ubuntu-24.04    Stopped         2

Move file to new location:
> move ext4.vhdx D:\WSL\

Unregister old installation, register new one and set it as default:
> wsl --unregister Ubuntu-24.04  
> wsl --import-in-place MyUbuntu D:\WSL\ext4.vhdx  
> wsl --set-default MyUbuntu  

### Advanced

For advanced WSL settings, see original documentation: <https://learn.microsoft.com/en-us/windows/wsl/wsl-config>  

## SD.Next Installation

### Install SD.Next

Start from Windows using WSL shortcut or from command prompt:
> wsl --distribution MyUbuntu --user myuser

Then in `bash`:

> cd  
> git clone <https://github.com/vladmandic/sdnext/> sdnext  
> cd sdnext  
> ./webui.sh --debug  

    Create and activate python venv
    Launching launch.py...
    Starting SD.Next
    Logger: file="/home/vlado/sdnext/sdnext.log" level=DEBUG size=64 mode=create
    Python 3.10.12 on Linux
    Version: app=sd.next updated=2024-04-06 hash=e783b098 branch=master url=https://github.com/vladmandic/sdnext//tree/master
    Platform: arch=x86_64 cpu=x86_64 system=Linux release=5.15.150.1-microsoft-standard-WSL2 python=3.10.12
    ...
    nVidia CUDA toolkit detected: nvidia-smi present
    ...
    Device: device=NVIDIA GeForce RTX 4090 n=1 arch=sm_90 cap=(8, 9) cuda=12.1 cudnn=8902 driver=551.86
    ...
    Local URL: http://127.0.0.1:7860/
    ...
    Startup time: 10.98 torch=1.90 gradio=0.40 libraries=0.88 extensions=0.52 face-restore=6.00 ui-en=0.09 ui-control=0.06 ui-extras=0.13 ui-settings=0.13 ui-extensions=0.25 launch=0.21 api=0.05 app-started=0.12

*Note*: This installs SD.Next into `/home/myuser/sdnext`, but you can use any path you prefer.  

Open your browser and navigate to the shown URL.

### Configure SD.Next

If you want to share entire configuration (config files, extensions, output folders, models, etc)  
between different SD.Next installations, start SD.Next with `--data-dir`.  

For example, to access previous Windows data on `C:\SDNext`, use `./webui.sh --data-dir /mnt/c/SDNext`

If you only want to share models, use `--model-dir`, for example `./webui.sh --model-dir /mnt/c/SDNext/models`.

## Additional Info

### Additional Packages

If you use a different distro, you may need extra packages such as:

- upgrade Python (if it is below 3.9) or downgrade Python (if it is above 3.12)

> sudo apt install python3.11 python3.11-venv python3-pip  
> export PYTHON=/usr/bin/python3.11

and potentially manually install nvidia libraries

> sudo apt install nvidia-cudnn libgl1

### Memory Optimizations

See [Malloc](Malloc) for details on how to optimize memory usage  

### Dev vs Master

To switch to the development branch:

> git pull
> git checkout dev

To switch back to `master`:

> git checkout master

### Faster Storage Access

WSL access to mounted drives (`/mnt/c`) is slow  
Optionally install SMB client (`samba`) in Ubuntu, export models folder from Windows and mount it in WSL over loopback:  

1. Select a folder in Windows you'd like to access from WSL and create a share for that folder  

2. Make sure you have the cifs tools installed for mounting the folder:  

> sudo apt install cifs-utils

1. Create credentials file `.cred` in your home folder (for example `/home/myuser/.cred`) with the following content:

    touch .cred
    chmod 600 .cred
    echo "username=yourwindowsusername" >> .cred
    echo "password=yourwindowspassword" >> .cred

> [!TIP] How to get internal-loopback IP of your Windows host?
> `ip route show | grep -i default | awk '{ print $3}'`

1. Then mount the folder in WSL:

    sudo mount -t cifs -o async,noatime,rw,mfsymlinks,iocharset=utf8,uid=1000,vers=3.1.1,cache=loose,nostrictsync,resilienthandles,cred=/home/myuser/.cred //$HOST_IP/Models /mnt/models