Skip to content

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 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

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