Set Up Loss Prevention on Windows 11 with WSL2#
This guide takes a clean Windows 11 machine to a working Loss Prevention environment under WSL2. It is written for someone who has never used WSL before.
Before make benchmark, also complete the hardware metrics prerequisites.
Windows GPU counters, optional GPU power sensors, and native Windows Performance Counter
Monitor (PCM) need separate host-side setup. Collection then starts and stops automatically
with the benchmark; no separate collector command is needed during a run. See
WSL benchmark metrics for outputs and limitations. The
Makefile detects WSL2 automatically from the Microsoft kernel; no flag is needed.
Follow the steps in order. Several of them fail in confusing ways if done out of sequence — particularly the proxy configuration, which must come before any download.
Contents#
Conventions#
Commands are labeled by where they run:
Label |
Where |
|---|---|
PowerShell |
Windows PowerShell or Terminal, on the Windows side |
Ubuntu |
Inside the WSL2 Ubuntu distribution |
Getting these mixed up is the single most common early mistake.
Values you must change for your site#
Most URLs in this guide are public upstream endpoints and are identical on every machine. A small number are site-specific and are the most likely reason the guide fails somewhere else. Every occurrence below is marked with a ⚙️ note.
Placeholder used here |
What it is |
How to find yours |
|---|---|---|
|
Example proxy URL; replace the host and port with your site’s values |
|
|
Reserved example values for the |
Your own internal DNS suffix and network ranges |
PAC URL |
Proxy auto-configuration file |
|
|
Windows profile path |
Use |
Discover everything at once. In PowerShell:
netsh winhttp show proxy
Get-ItemProperty "HKCU:\Software\Microsoft\Windows\CurrentVersion\Internet Settings" |
Select-Object ProxyServer, AutoConfigURL
In Ubuntu, once a distribution exists:
echo "$HTTP_PROXY"
echo "$WSL_PAC_URL"
These are constant everywhere — never edit them: api.github.com,
download.docker.com, archive.ubuntu.com, github.com/intel-retail/loss-prevention,
openvino/ubuntu24_dev. The service names rabbitmq, minio-service,
rtsp-streamer, ovms-vlm, and model-downloader in every NO_PROXY are Docker
Compose service names from src/docker-compose.yml and must be kept as-is.
1. Elevation and virtualization#
WSL2 is a lightweight virtual machine. Getting it installed means satisfying three independent requirements, in this order:
Layer |
What it is |
How to enable |
Reboot |
|---|---|---|---|
VT-x |
CPU feature, a firmware setting |
BIOS/UEFI only |
Yes, into BIOS |
Windows features |
|
|
Yes, normal reboot |
WSL package |
the |
|
No |
These are not alternatives. dism cannot switch on VT-x, and enabling the Windows
features while VT-x is off leaves you with a WSL that installs cleanly and then refuses
to boot a distribution.
1a. Open an elevated PowerShell#
Everything in this section fails with Error: 740 — Elevated permissions are required
from a normal shell.
Select Windows Start menu, type powershell, right-click Windows PowerShell, and
Run as administrator. Or from an existing window:
Start-Process powershell -Verb RunAs
To confirm it worked:
whoami /groups | findstr /i "High Mandatory"
The result must print a line containing High Mandatory Level. Nothing printed means the
window is not elevated.
Caution
Remote machines: an SSH session (MobaXterm, OpenSSH) cannot elevate — UAC needs
an interactive desktop to draw the consent dialog, and there is no CLI workaround. Use
RDP, which creates a real interactive session and supports UAC normally. If the
account is not listed by net localgroup Administrators, stop here.
1b. Point WinHTTP at the proxy#
An elevated shell uses the machine’s WinHTTP proxy configuration, not your browser’s,
and by default that is empty. Skip this on a corporate network and the WSL downloader
fails with The certificate authority is invalid or incorrect:
netsh winhttp import proxy source=ie
netsh winhttp show proxy
If it still reports Direct access (no proxy server), set it explicitly:
netsh winhttp set proxy proxy-server="http=proxy.example.com:PORT;https=proxy.example.com:PORT" bypass-list="*.example.com;localhost;127.0.0.1;<local>"
Note
⚙️ Site-specific. Replace proxy.example.com:PORT and the bypass list with your
own. Find them with:
Get-ItemProperty "HKCU:\Software\Microsoft\Windows\CurrentVersion\Internet Settings" |
Select-Object ProxyServer, AutoConfigURL
If only AutoConfigURL is set, open that PAC URL in a browser and read the proxy host
and port out of the JavaScript.
Check the proxy actually reaches the download host before going further:
curl.exe -sS -o NUL -w "%{http_code}`n" -x http://proxy.example.com:PORT https://github.com
Replace the example host and PORT with the proxy host and port reported by your
settings or PAC file. A 200 confirms the proxy reaches the destination; a 403 means
it refuses that destination.
1c. Check firmware virtualization#
Run this to check virtualization:
systeminfo | findstr /i "Hyper-V"
Output |
Meaning |
Action |
|---|---|---|
|
VT-x is on and a hypervisor is running |
Continue to 1d |
A list ending |
VT-x is off |
Reboot into BIOS/UEFI, enable Intel Virtualization Technology (VT-x), then resume here |
If virtualization is off, you have to enable it in BIOS — there is no Windows command for it.
1d. Enable the Windows features and install the WSL package#
One command normally does both:
wsl.exe --install --no-distribution
On a corporate network this often fails at the download half with
The certificate authority is invalid or incorrect or Forbidden (403). The WSL
downloader performs its own strict certificate validation and rejects the TLS-inspected
chain, even when the corporate CA is trusted machine-wide. Retrying will not help.
Split the two jobs instead. The Deployment Image Servicing and Management (DISM) tool enables the features and needs no network:
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
Then fetch the package with curl.exe, which ships with Windows and validates against
the Windows certificate store — the same store your browser uses, so the inspected chain
is accepted:
$json = curl.exe -sS -x http://proxy.example.com:PORT https://api.github.com/repos/microsoft/WSL/releases/latest | ConvertFrom-Json
$url = ($json.assets | Where-Object { $_.name -like '*x64.msi' }).browser_download_url
$url
curl.exe -L -x http://proxy.example.com:PORT -o "$env:TEMP\wsl.msi" $url
(Get-Item "$env:TEMP\wsl.msi").Length
msiexec /i "$env:TEMP\wsl.msi" /qn /norestart
Expect roughly a 100–150 MB download. A few kilobytes means you downloaded the proxy’s block page rather than the installer.
Note
⚙️ Site-specific. Replace http://proxy.example.com:PORT with the proxy URL
confirmed in step 1b. The api.github.com URL is
universal, and the MSI URL is deliberately not hardcoded: the API query resolves the
current version’s browser_download_url, so it stays correct as WSL releases change. Do not
replace it with a literal filename.
winget install --id Microsoft.WSL is a third option. It uses yet another HTTP stack
and sometimes succeeds where both others fail.
1e. Reboot#
The feature changes do not take effect until you do:
shutdown /r /t 0
1f. Verify#
In an elevated shell (this query also needs it):
dism /online /get-featureinfo /featurename:VirtualMachinePlatform
Expected: State : Enabled.
Then ask WSL itself:
wsl --version
wsl --status
|
Meaning |
Action |
|---|---|---|
|
Step 1 complete |
Go to step 2 |
|
The step 1d download half did not succeed |
Install the MSI |
|
The package is installed but the Windows features are not |
Run the command below, then reboot |
|
VT-x is off in firmware |
See step 1c, enable in BIOS |
The third row is the common one after installing via MSI. wsl.exe is now present and
reporting on its own environment. Its full message is:
WSL1 is not supported with your current machine configuration.
Please enable the "Windows Subsystem for Linux" optional component to use WSL1.
WSL2 is unable to start since virtualization is not enabled on this machine.
Please ensure the "Virtual Machine Platform" optional component is enabled and
virtualization is turned on in your computer's firmware settings.
Because the package is already local, this command no longer needs to download anything — it only flips the two optional components, so it succeeds even on a network where 1d failed:
wsl.exe --install --no-distribution
shutdown /r /t 0
Re-run wsl --status after the reboot. It should now report Default Version: 2.
2. Install WSL2 and Ubuntu 24.04#
PowerShell:
wsl --set-default-version 2
wsl --list --online
wsl --install -d Ubuntu-24.04
The installer prompts for a Linux username and password. These are independent of
your Windows account. Remember the password — it is your sudo password.
Record your version baseline:
wsl --version
wsl -l -v
Example output:
WSL version: 2.7.12.0
Kernel version: 6.18.33.2-2
WSLg version: 1.0.73.2
Direct3D version: 1.611.1-81528511
Windows version: 10.0.26200.9168
Ubuntu — confirm the distribution launched and identifies itself:
lsb_release -a
uname -r
Expected: Ubuntu 24.04 LTS (codename noble).
Important
Do not run apt update or apt upgrade yet. On a corporate network those will
partially fail in ways that are hard to interpret. Configure the proxy first — the
system update is the last part of step 3.
Type exit to return to PowerShell.
3. Proxy configuration#
Do this before anything else that touches the network. On a corporate network, skipping it produces misleading failures much later.
Why this trips people up#
On some networks, plain HTTP may work directly while HTTPS is blocked. Ubuntu’s own
package repositories may use plain HTTP, so sudo apt update can appear to succeed:
Hit:1 http://archive.ubuntu.com/ubuntu noble InRelease <-- HTTP repository succeeds
Err:6 https://download.docker.com/linux/ubuntu noble InRelease <-- HTTPS repository times out
Could not connect to download.docker.com:443, connection timed out
A successful apt update does not prove your network is configured.
If you are not behind a proxy, skip to step 4.
3a. Windows side — .wslconfig#
By default WSL2 uses NAT, and corporate endpoint-security agents frequently drop that traffic. Mirrored networking makes WSL share the Windows network stack directly.
Note
Mirrored networking requires WSL 2.0.0+ and Windows build 22621+.
Check with wsl --version and [System.Environment]::OSVersion.Version if unsure.
On older builds, omit networkingMode, dnsTunneling, and firewall, and set the
proxy manually in step 3b.
Create or edit C:\Users\<YourName>\.wslconfig:
[wsl2]
networkingMode=mirrored
dnsTunneling=true
autoProxy=true
firewall=true
Note
⚙️ Machine-specific path. Rather than typing your username, let PowerShell resolve it — this writes the same file on any machine:
@"
[wsl2]
networkingMode=mirrored
dnsTunneling=true
autoProxy=true
firewall=true
"@ | Set-Content -Path "$env:USERPROFILE\.wslconfig" -Encoding ASCII
Get-Content "$env:USERPROFILE\.wslconfig"
On a remote machine this must be the profile of the account running WSL, not the one you connect from.
PowerShell — apply:
wsl --shutdown
Ubuntu — verify. The address should now match your Windows IPv4, not 172.x.x.x:
ip addr show eth0 | grep 'inet '
3b. Ubuntu shell — ~/.bashrc#
autoProxy=true injects HTTP_PROXY but not HTTPS_PROXY. Tools like curl read
HTTPS_PROXY for TLS connections, so without it they connect directly to port 443 and
hang. Mirror the value:
cat >> ~/.bashrc <<'EOF'
# WSL autoProxy sets HTTP_PROXY but not HTTPS_PROXY - mirror it
if [ -n "$HTTP_PROXY" ]; then
export HTTPS_PROXY="${HTTPS_PROXY:-$HTTP_PROXY}"
export http_proxy="$HTTP_PROXY"
export https_proxy="$HTTPS_PROXY"
export NO_PROXY="localhost,127.0.0.1,::1,.example.com,192.0.2.0/24,rabbitmq,minio-service,rtsp-streamer,ovms-vlm,model-downloader"
export no_proxy="$NO_PROXY"
fi
EOF
source ~/.bashrc
Verify:
env | grep -i proxy
curl -sI --max-time 15 https://download.docker.com/linux/ubuntu/gpg | head -1
The curl must return HTTP/1.1 200 or HTTP/2 200. A hang means HTTPS is still
going direct.
Note
Find your proxy URL from echo $HTTP_PROXY, or inspect the PAC file WSL exposes as
$WSL_PAC_URL. On Windows, netsh winhttp show proxy and the Internet Settings
ProxyServer and AutoConfigURL values show the configured proxy or PAC URL. If only
a PAC URL is available, inspect its script to find the proxy host and port.
⚙️ Site-specific. The NO_PROXY list above mixes two kinds of entry. Replace
.example.com and 192.0.2.0/24 with your own internal domain and network ranges.
Keep rabbitmq, minio-service, rtsp-streamer, ovms-vlm, and model-downloader —
those are Compose service names from src/docker-compose.yml, identical on every
machine, and routing them through a proxy breaks inter-container traffic.
Check your current values with:
echo "$HTTP_PROXY"
echo "$WSL_PAC_URL"
3c. apt — its own configuration file#
apt does not read shell environment variables. It needs its own file. This is
separate from step 3b and both are required:
sudo tee /etc/apt/apt.conf.d/95proxies > /dev/null <<'EOF'
Acquire::http::Proxy "http://proxy.example.com:PORT";
Acquire::https::Proxy "http://proxy.example.com:PORT";
EOF
Note
⚙️ Site-specific. Substitute your own proxy. Because the heredoc is quoted
(<<'EOF'), $HTTP_PROXY would be written literally rather than expanded — so if you
want it filled in from the environment, drop the quotes:
sudo tee /etc/apt/apt.conf.d/95proxies > /dev/null <<EOF
Acquire::http::Proxy "$HTTP_PROXY";
Acquire::https::Proxy "$HTTPS_PROXY";
EOF
Always cat the file afterwards to confirm real values landed, not empty strings.
3d. Force IPv4#
WSL2 has no IPv6 route, so every apt download wastes around 30 seconds failing over eight IPv6 addresses before trying IPv4. Force IPv4 with:
sudo tee /etc/apt/apt.conf.d/99force-ipv4 > /dev/null <<'EOF'
Acquire::ForceIPv4 "true";
EOF
Verify both files:
cat /etc/apt/apt.conf.d/95proxies /etc/apt/apt.conf.d/99force-ipv4
3e. Update the base system#
Only now is it safe to run this — every download path is configured:
sudo apt update
sudo apt upgrade -y
apt update must complete with no Err: lines. Warnings about missing repositories
you have not added yet are fine; connection timeouts are not.
The four proxy contexts#
Proxy settings live in four unrelated places. Configuring one tells you nothing about the others:
Context |
Consumer |
Location |
Step |
|---|---|---|---|
Shell |
|
|
|
apt |
|
|
|
Daemon |
|
|
|
Build |
|
|
Steps 7 and 8 come later because those paths do not exist until Docker is installed.
Caution
sudo strips proxy environment variables. Use sudo -E for any command that needs
network access.
4. Base packages#
sudo apt install -y \
build-essential make git curl wget unzip \
jq python3 python3-pip python3-venv \
ca-certificates gnupg lsb-release x11-xserver-utils
Package |
Used by |
|---|---|
|
every workflow command ( |
|
|
|
|
|
model and video downloads |
|
the repository and the |
|
|
Verify:
make --version && jq --version && python3 --version && git --version
5. Enable systemd#
Docker Engine runs as a systemd service. WSL2 does not enable systemd by default, so
enable it in /etc/wsl.conf:
sudo tee /etc/wsl.conf > /dev/null <<'EOF'
[boot]
systemd=true
[interop]
appendWindowsPath=true
EOF
PowerShell — a full shutdown is required; closing the terminal is not enough:
wsl --shutdown
Reopen Ubuntu and verify:
ps -p 1 -o comm=
systemctl list-units --type=service | head
ps -p 1 -o comm= must print systemd. If you see
System has not been booted with systemd, the shutdown did not take effect.
6. Install Docker Engine#
Why Docker Engine and not Docker Desktop#
Docker Desktop runs its daemon in a separate hidden distribution (docker-desktop),
not in your Ubuntu. For the GPU work in step 11 you will bind-mount /usr/lib/wsl/lib
and pass --device=/dev/dxg; cross-distribution path translation makes failures much
harder to diagnose. With Docker Engine installed inside Ubuntu-24.04, the daemon sees exactly the
same devices and filesystem you do.
Caution
Do not install both. Two daemons will conflict.
Add Docker’s GPG key#
sudo install -m 0755 -d /etc/apt/keyrings
sudo -E curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
-o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
Verify before continuing. A timed-out curl leaves an empty file, and the resulting
apt error is misleading:
head -1 /etc/apt/keyrings/docker.asc
Must print -----BEGIN PGP PUBLIC KEY BLOCK-----.
Add the repository and install#
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] \
https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo $VERSION_CODENAME) stable" \
| sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io \
docker-buildx-plugin docker-compose-plugin
Enable non-root access#
sudo usermod -aG docker $USER
sudo systemctl enable --now docker
Group membership is only read at login. PowerShell:
wsl --shutdown
Reopen Ubuntu and confirm the group and the service. These are local checks and need no network:
id -nG | tr ' ' '\n' | grep docker
systemctl is-active docker
Expect docker and active. If the group is missing, the shutdown did not take effect.
Caution
Do not work around permission errors with sudo docker. Running as root creates
root-owned files in models/ and results/, which breaks later steps.
The full end-to-end check comes at the end of step 8 — docker run hello-world has to
pull an image, which cannot work until the daemon proxy is configured.
7. Docker daemon proxy#
Required for docker pull. The daemon is a system service and does not inherit your
shell environment:
sudo mkdir -p /etc/systemd/system/docker.service.d
sudo tee /etc/systemd/system/docker.service.d/proxy.conf > /dev/null <<'EOF'
[Service]
Environment="HTTP_PROXY=http://proxy.example.com:PORT"
Environment="HTTPS_PROXY=http://proxy.example.com:PORT"
Environment="NO_PROXY=localhost,127.0.0.1,.example.com,rabbitmq,minio-service,rtsp-streamer,ovms-vlm,model-downloader"
EOF
sudo systemctl daemon-reload
sudo systemctl restart docker
Note
⚙️ Site-specific. Replace http://proxy.example.com:PORT and the .example.com
entry with your own;
keep the Compose service names. Confirm the values you are about to write first with
echo "$HTTP_PROXY".
Verify:
docker info | grep -i proxy
You should see HTTP Proxy, HTTPS Proxy, and No Proxy lines. If they are absent,
the drop-in did not load.
8. Docker build-time proxy#
Each RUN instruction in a Dockerfile executes in a throwaway container with a clean
environment. It does not inherit your shell’s proxy settings.
The Makefile and Compose file already pass HTTP_PROXY/HTTPS_PROXY as build arguments
for the project’s own images, but coverage has gaps:
With
WSL2=false REGISTRY=false,make build-benchmarkdelegates to theperformance-toolssubmodule’s Makefile, which is outside this repository’s proxy plumbing. On WSL2, it instead uses the Windows Python executable configured byWINDOWS_PYTHONin the root Makefile and installs its Python dependencies; Windows Python needs its own working network/proxy configuration. Docker proxy settings do not configure Windows pip.Only
rtsp-streamerpasses the lowercasehttp_proxy/https_proxyvariants;curlreads lowercasehttp_proxyonly, soRUN curl http://...in the other images would bypass the proxy.NO_PROXYis not passed as a build argument anywhere.
Setting the CLI-level configuration covers all of these uniformly:
mkdir -p ~/.docker
cat > ~/.docker/config.json <<'EOF'
{
"proxies": {
"default": {
"httpProxy": "http://proxy.example.com:PORT",
"httpsProxy": "http://proxy.example.com:PORT",
"noProxy": "localhost,127.0.0.1,.example.com,rabbitmq,minio-service,rtsp-streamer,ovms-vlm,model-downloader"
}
}
}
EOF
Note
⚙️ Site-specific. Same substitution as step 7 — proxy host,
port, and .example.com.
This file is JSON, so a trailing comma or an unescaped value breaks every docker
command, not just builds. Validate it after writing:
jq . ~/.docker/config.json
Verify Docker end to end#
Only now can Docker actually reach a registry. Run these in order:
id -nG | tr ' ' '\n' | grep docker
docker run hello-world
docker compose version
docker buildx version
docker run hello-world is the real test — it pulls from Docker Hub, so it exercises the
daemon proxy from step 7. A hang or TLS handshake timeout means that drop-in is wrong
or did not load; re-check docker info | grep -i proxy.
docker compose version must report v2.24.4 or newer — the Makefile uses
docker compose (space, not hyphen) throughout, and src/docker-compose-wsl2.yml
relies on the include top-level element and the !override merge tag, which earlier
v2 releases reject. If your version is older, upgrade docker-compose-plugin from
the Docker apt repository configured in step 6.
9. Memory and CPU tuning#
The Vision Language Model (VLM) workload loads a 7B parameter model. Defaults are not sufficient.
Edit C:\Users\<YourName>\.wslconfig on the Windows side, merging with the
networking settings from step 3a:
[wsl2]
memory=48GB
processors=12
swap=16GB
networkingMode=mirrored
dnsTunneling=true
autoProxy=true
firewall=true
Note
localhostForwarding is unnecessary when networkingMode=mirrored is set.
⚙️ Machine-specific. Use $env:USERPROFILE\.wslconfig for the path. The
memory, processors, and swap values must suit your hardware: check with
Get-CimInstance Win32_ComputerSystem | Select TotalPhysicalMemory and
$env:NUMBER_OF_PROCESSORS, then leave headroom for Windows — roughly 75% of RAM and
total cores is a safe ceiling.
PowerShell:
wsl --shutdown
Ubuntu — verify:
free -h
nproc
df -h /
The repository plus models needs roughly 300 GB. df -h / reports free space inside
the WSL filesystem, not free space on the Windows drive storing its virtual disk. Check
that host drive separately in PowerShell (for example, Get-PSDrive C if the
distribution is stored on C:). Both the WSL filesystem and its Windows host drive need sufficient
space.
10. Clone the repository#
cd ~
git clone https://github.com/intel-retail/loss-prevention.git
cd loss-prevention
git submodule update --init --recursive
Important
Never clone into
/mnt/c/.... Windows drives are reached through a slow translation layer. Always use~, which is the native Linux filesystem.The submodule is mandatory.
performance-tools/holds every benchmark script.
Verify the submodule checked out:
ls performance-tools/benchmark-scripts | head
You should see benchmark.py and format_avc_mp4.sh. An empty directory means the
submodule did not initialize.
Record your baseline:
git rev-parse --short HEAD
git submodule status
Optional: repository-scoped environment#
The Makefile reads an optional .env file. Proxy variables do not need to go here —
make already imports them from your shell environment. Use .env only for values that
should not be global, such as secrets and optional WSL2 host configuration:
# .env (do not commit)
HUGGINGFACE_TOKEN=hf_xxxxxxxx
The Makefile detects WSL2 automatically and selects src/docker-compose-wsl2.yml
instead of the native src/docker-compose.yml. The WSL2 Compose file replaces native Linux /dev/dri
device mappings with WSL2’s /dev/dxg and mounts the WSL graphics libraries
and driver helper libraries. OpenCL configuration and userspace runtimes come
from the container images, not host OpenCL bind mounts. CPU workloads remain CPU workloads
because the device is selected by the workload JSON.
11. GPU and NPU verification#
This is the decisive check for the whole adaptation of Loss Prevention to WSL2.
Windows drivers and container userspace runtimes#
WSL GPU access uses the Windows graphics driver and /dev/dxg, not a native
Linux GPU kernel driver. WSL exposes graphics libraries under /usr/lib/wsl/lib
and driver helpers under /usr/lib/wsl/drivers. Keep the Windows graphics driver
up to date; do not install a native Linux kernel driver to replace it.
OpenCL and Level Zero userspace runtimes are separate from that kernel driver.
The container images must provide compatible runtimes and ICD configuration.
The WSL Compose override retains the image’s /etc/OpenCL and
/usr/lib/x86_64-linux-gnu/intel-opencl contents instead of mounting host copies
over them. These host directories are not prerequisites and should not be created
just to satisfy Docker mounts. Host userspace packages do not provision container
runtimes.
For lp-pipeline-runner, the WSL startup wrapper prepends both WSL library
directories to the image’s existing LD_LIBRARY_PATH before running the normal
pipeline script. The other GPU services also include the WSL library paths.
GPU enumeration in the actual deployment images remains a required host check;
Compose parsing alone does not establish runtime compatibility.
If the Windows-provided WSL libraries or /dev/dxg are missing, update the Intel
graphics driver on Windows, then run wsl --shutdown. If the device exists but
OpenVINO™ Toolkit (OpenVINO™) cannot enumerate a GPU, inspect the container’s runtime
and ICD files.
Note
NPU workloads remain unsupported by this WSL setup.
11a. Host device check#
ls -l /dev/dxg
ls -l /usr/lib/wsl/lib/
ls -l /usr/lib/wsl/drivers/
ls /dev/dri 2>&1
ls /dev/accel 2>&1
Expected results:
Path |
Expected |
Meaning |
|---|---|---|
|
exists |
the WSL GPU device — replaces |
|
populated |
WSL graphics bridge libraries such as |
|
populated |
WSL GPU driver helpers such as |
|
absent |
expected; this is why the Compose device mappings need changing |
|
likely absent |
the NPU finding |
If /dev/dxg is missing, stop here and update the Windows graphics driver.
11b. OpenVINO™ device enumeration#
docker run --rm \
--device=/dev/dxg \
-v /usr/lib/wsl/lib:/usr/lib/wsl/lib:ro \
-v /usr/lib/wsl/drivers:/usr/lib/wsl/drivers:ro \
intel/dlstreamer:2026.2.0-ubuntu24 \
bash -lc '. /opt/intel/openvino/setupvars.sh 2>/dev/null || true; \
export LD_LIBRARY_PATH=/usr/lib/wsl/lib:/usr/lib/wsl/drivers:/usr/lib/openvino-2026.2.0${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}; \
python3 -c "import openvino as ov; print(ov.Core().available_devices)"'
Want: ['CPU', 'GPU']
If only ['CPU'] appears, do not run GPU workloads. Inspect the plugin and driver
runtime with:
docker run --rm \
--device=/dev/dxg \
-v /usr/lib/wsl/lib:/usr/lib/wsl/lib:ro \
-v /usr/lib/wsl/drivers:/usr/lib/wsl/drivers:ro \
intel/dlstreamer:2026.2.0-ubuntu24 \
bash -lc 'export LD_LIBRARY_PATH=/usr/lib/wsl/lib:/usr/lib/wsl/drivers:/usr/lib/openvino-2026.2.0${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}; \
ldd /usr/lib/openvino-2026.2.0/libopenvino_intel_gpu_plugin.so | grep "not found" || true; \
python3 -c "import openvino as ov; print(ov.Core().available_devices)"'
11c. NPU#
ls /dev/accel 2>&1
lsmod | grep -i vpu
If NPU does not appear in the OpenVINO™ device list, that is the expected result on
current WSL2 builds, not a mistake on your part. Intel NPU passthrough uses a different
mechanism from GPU passthrough and may not be available for your driver and kernel
combination. A documented “not supported” is a valid outcome.
11d. Record the baseline#
{
echo "=== /dev/dxg ===" ; ls -l /dev/dxg 2>&1
echo "=== /dev/dri ===" ; ls -l /dev/dri 2>&1
echo "=== /dev/accel ===" ; ls -l /dev/accel 2>&1
echo "=== /usr/lib/wsl/lib ==="; ls /usr/lib/wsl/lib/
echo "=== kernel ===" ; uname -r
} | tee ~/wsl-accel-baseline.txt
12. Smoke test#
Run in order, stopping at the first failure:
cd ~/loss-prevention
# 1. Docker works
docker run hello-world
# 2. The Makefile parses and resolves variables
make -n run-lp | head -20
# 3. Config validators work (proves python3 and jq are fine)
make validate-all-configs
# 4. What devices does the repo think you have?
make check-device-env
# 5. Sample videos - small download, fast feedback
make download-sample-videos
Optional: render mode#
WSLg can display the annotated stream for CPU workloads. xhost is provided by
x11-xserver-utils, which is installed in step 4. Confirm that WSLg set
a display:
echo "$DISPLAY"
xhost +local:docker
Run the CPU object-detection workload with rendering enabled:
RENDER_MODE=1 DISPLAY=:0 make run-lp \
CAMERA_STREAM=camera_to_workload_asc_object_detection.json \
WORKLOAD_DIST=workload_to_pipeline_asc_object_detection_cpu.json
When testing a change to src/gst-pipeline-generator.py, use REGISTRY=false so
Docker rebuilds lp-pipeline-runner from the current checkout. The registry image does
not contain uncommitted or newly pulled local source changes:
make down-lp
REGISTRY=false RENDER_MODE=1 DISPLAY=:0 make run-lp \
CAMERA_STREAM=camera_to_workload_asc_object_detection.json \
WORKLOAD_DIST=workload_to_pipeline_asc_object_detection_cpu.json
For the WSLg display path, the generated pipeline must include videoconvert before
the automatic video sink. Verify it in the running container:
docker compose -f src/docker-compose-wsl2.yml exec lp-pipeline-runner \
grep -n 'gvawatermark.*videoconvert.*ximagesink' \
/home/pipeline-server/pipelines/pipeline.sh
Troubleshooting#
MinIO restarts after the image update: backend write permission denied#
After switching from the previous MinIO image to the Chainguard image, an existing
data volume may still be owned by the previous container user. make run-lp can
then fail with dependency failed to start: container src-minio-service-1 is unhealthy.
The MinIO logs identify this case with:
Error: unable to rename (/data/.minio.sys/tmp -> /data/.minio.sys/tmp-old/...) file access denied
FATAL Unable to initialize backend: Unable to write to the backend
This is a storage-permissions failure, not a /dev/tcp health-check failure. MinIO
exits because it cannot write to /data, and its restart policy restarts the
container. Changing the health check will not fix that startup error. The same
issue can occur on native Linux; it depends on volume ownership, not WSL2 detection.
Run the following commands in Ubuntu, on the affected machine. The examples
use the default container name src-minio-service-1 and volume src_minio_data.
If your Compose project uses another name, substitute the actual names.
Confirm the error, the mounted volume, and the image’s runtime UID/GID:
docker logs --tail 100 src-minio-service-1 docker inspect src-minio-service-1 --format 'User={{.Config.User}} Mounts={{json .Mounts}}' MINIO_IMAGE=$(docker inspect src-minio-service-1 --format '{{.Image}}') docker run --rm --network none --entrypoint /bin/sh "$MINIO_IMAGE" -c 'id'
For the pinned Chainguard image, the verified values are
User=65532,uid=65532(nonroot) gid=65532(nonroot), and the named volume mounted at/dataissrc_minio_datawithRW=true. The temporary container used foriddoes not mount your data. Do not use the repair command unchanged if these values differ; use the actual volume name and the UID/GID that the service runs as.Stop MinIO before modifying its storage. Back up the volume first if it contains important data:
docker stop src-minio-service-1
Repair ownership and owner permissions without deleting stored data:
docker run --rm --user 0:0 --network none \ --mount type=volume,source=src_minio_data,target=/data \ alpine:3.22 \ sh -c 'chown -R 65532:65532 /data && chmod -R u+rwX /data'
Docker may need to pull
alpine:3.22; its daemon proxy must already be configured. Root is used only in this temporary repair container. MinIO continues to run as non-root. Stop here if the repair command fails.Start MinIO and inspect recent startup logs:
docker start src-minio-service-1 docker logs --since 1m --tail 50 src-minio-service-1
Allow approximately 30 seconds for the health check, then inspect its result:
docker inspect src-minio-service-1 --format '{{json .State.Health}}'
Once it reports
healthy, rerun your originalmake run-lpcommand to start the services that were blocked by MinIO. If it remains unhealthy, inspect the new server logs and health-check output before making further changes.
This is a one-time repair for the affected volume, not a step required on every
run. Ownership persists across container restarts, recreation, and normal Compose
down/up operations. Restored data with different ownership or a future runtime
UID change may require another migration. Keep the current health check unchanged;
do not use down -v, delete the volume, apply chmod 777, or permanently run MinIO
as root to resolve this error.