Applies to: Windows 11
Before you start, we strongly recommend reading Read this before installing PWstudio first to get the big picture. Some commands on this page are run in Windows PowerShell, and some are run inside WSL (which acts like its own Linux system) — please pay attention to which is which; the guide notes which environment each command belongs to.
First, check your Windows version number. Open cmd or powershell (type “powershell” into the Start menu search box to find it), and run:
winver # The version I'm using is: Windows 11 25H2 (26200.8655) or systeminfo | findstr "OS"
Running winver pops up a small window showing the version number directly. If nothing pops up, the command was typed wrong — check for extra spaces.
Installing drivers, activating Windows, tuning performance, setting up an input method, etc. are not covered here — they're basic OS-level setup unrelated to PWstudio.
WSL stands for Windows Subsystem for Linux — in short, it's the technology that lets you “run a Linux system inside Windows,” and PWstudio runs inside this Linux environment. All the commands below are run in PowerShell:
PowerShell in the Start menu, right-click it, and choose “Run as administrator” (important: you must use “Run as administrator” — opening it normally may cause later commands to fail due to insufficient permissions)wsl --update --pre-release
This command downloads an update over the network, which may take a minute or two depending on your network speed. Once it's done, it will say either that the update completed or that you already have the latest version — both are normal.
wsl --shutdown
This command normally produces no output — that's expected. It shuts down the WSL background service; the next time you open it, it will restart with the latest configuration.
wslc --version
The commands below are also run in PowerShell, to verify that the container feature is working correctly.
Verify CPU container functionality:
wslc run --rm swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/hello-world:latest
If you see text starting with “Hello from Docker!”, basic container functionality is working.
Verify GPU container functionality:
wslc run --rm --gpus all ` swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi
If you see a table with the GPU model, driver version, etc., the GPU can now be correctly recognized and used by the WSL container. If this produces an error, see chapter 7, “Troubleshooting,” below — it lists the two most common errors and how to fix them.
Installation instructions: click the link, Installing the server.py service on Linux, and follow the guide to set up the license service before moving to the next step.
Run in PowerShell (this step downloads the PWstudio GPU image from the registry; it's fairly large, so depending on your network speed it may take around ten minutes — please be patient and don't close the window partway through):
wslc pull ccr.ccs.tencentyun.com/lxkt/qflowgpu:latest
In PowerShell:
wslc run -d --name qflowgpu ` -v $env:TEMP\pwmat:/var/tmp/pwmat_host_secret:ro ` --ulimit memlock=-1:-1 --ulimit stack=-1:-1 --gpus all --shm-size=128G ` -e SELINUX=disabled -p 80:80 -p 81:81 -p 2297:2297 -p 5010:5010 ` --hostname=mstation ccr.ccs.tencentyun.com/lxkt/qflowgpu:latest
In cmd:
wslc run -d --name qflowgpu ^ -v %TEMP%\pwmat:/var/tmp/pwmat_host_secret:ro ^ --ulimit memlock=-1:-1 --ulimit stack=-1:-1 --gpus all --shm-size=128G ^ -e SELINUX=disabled -p 80:80 -p 81:81 -p 2297:2297 -p 5010:5010 ^ --hostname=mstation ccr.ccs.tencentyun.com/lxkt/qflowgpu:latest
Pick one of the two blocks above depending on whether you're using PowerShell or cmd (the regular command prompt) — don't run both. If there's no error, it will usually print a long string of characters (the container ID), which means the container has started running in the background.
The backtick ``` ` ``` (used at the end of each line in the PowerShell version) and the caret ``^`` (used at the end of each line in the cmd version) are each shell's “line continuation” character, meaning “this command isn't finished yet — the next line is still part of the same command.” Don't leave them out or delete them — we recommend copying and pasting the whole block at once.
If you see an error like this when running the verification command:
PS C:\WINDOWS\system32> wslc run --rm hello-world The operation could not be started because a required feature is not installed. Error code: HCS_E_SERVICE_NOT_AVAILABLE
Fix
Check and enable the required Windows feature: WSL 2 depends on the VirtualMachinePlatform feature
Open PowerShell as administrator and run the following command to enable it (if it's already enabled, the command will just report its status — no harm done):
Enable-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform -All
Be sure to restart your computer for the change to take effect. Once it's back up, reopen PowerShell and try the verification command from chapter 3 again.
If you see an error like this when running the GPU verification command:
PS C:\WINDOWS\system32> wslc run --rm --gpus all ` swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi Failed to initialize NVML: GPU access blocked by the operating system Failed to properly shut down NVML: GPU access blocked by the operating system
🔍 Why this happens
Accessing the physical GPU from inside WSL 2 requires the following conditions to be met, otherwise this error occurs:
1. The correct driver version: you need to install the NVIDIA driver specifically designed for WSL 2 on the Windows host machine — not inside the Linux distribution (e.g. Ubuntu) itself.
2. WSL 2 configuration: the WSL 2 virtualization platform feature must be correctly enabled.
🔧 Fix
Check and install the correct NVIDIA driver (on the Windows host — i.e. inside your regular Windows desktop system, not inside WSL)
Go to the NVIDIA website and download the “NVIDIA CUDA on WSL” driver, or a Windows driver package that includes WSL support (usually version 570 or later)
Go to the NVIDIA website → select the correct GPU model → Key step: in the Operating System drop-down, choose Windows 11 or Windows 10
Choose the Game Ready driver (both Game Ready and Studio drivers already include support for CUDA and DirectML under WSL 2)
For running GPU compute or AI workloads, the Game Ready driver tends to be the better choice
Once downloaded and installed, restart your computer once, then go back to chapter 3 and verify GPU container functionality again.
Once the container has started successfully, the next steps are accessing Qstudio/Qflow through a web browser, and logging into the container with an SSH tool (e.g. MobaXterm) to upload/download files. Jump to: 5. Logging into the container, uploading/downloading files and follow the guide to the end. If you don't yet know how to use MobaXterm, read the MobaXterm beginner tutorial first.