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:

If you're installing on your own computer: right-click the Start button and choose to open PowerShell as administrator; or search for PowerShell in the “Start” menu, right-click it and choose “Run as administrator” to open the terminal.

If you're installing on a server with a Windows system installed: you first need to connect to the remote server following the steps below.

(1) Open the Remote Desktop Connection tool
• Press the Win + R keys on your keyboard to open the “Run” dialog box.
• In the dialog box that pops up, type mstsc, then click “OK” or press Enter.

(2) Enter the server information
• In the “Remote Desktop Connection” window that pops up, find the “Computer” field.
• Enter the target server's IP address: for example 192.168.97.23.
• Click “Show Options” in the lower-left corner to expand more settings. In the “User name” field, enter the corresponding username, for example lxkt.
• Click “Connect”.

(3) Enter the login credentials
• The system pops up a “Windows Security” window, asking for the username's password as the credential.
• In the “User name” field, enter lxkt (if you already filled it in the previous step, it will be shown automatically here).
• In the “Password” field, enter the password, for example lxkt.
• Once you've confirmed the information is correct, click “OK”.

(4) Confirm the security certificate
• If this is the first time you're connecting to this server, the system may prompt “Cannot verify the identity of the remote computer. Do you want to connect anyway?”.
• This is a normal security reminder — after checking that the IP address is correct, click “Yes” to continue the connection.

After the connection succeeds, you can log into the remote server's Windows desktop. On the remote server, right-click the Start button and open PowerShell as administrator; or search for PowerShell in the “Start” menu, right-click it and choose “Run as administrator” to open the terminal.

1. If the system doesn't have WSL yet, you need to run the following command first to install it

wsl --install

2. Update to the WSL pre-release build: run the following command

wsl --update --pre-release

3. Restart the WSL service: after the update finishes, run this command to apply the change

wsl --shutdown

4. Verify that wslc is available: close and reopen your terminal (PowerShell or Windows Terminal)

wslc --version

• If you see a version number like 2.9.4, the WSL container feature is ready and you can move on.
• If it says the command isn't found, the update step above probably didn't complete successfully, or you may need to restart your computer and try again.

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

Before starting the container, you first need to run ipconfig in the host's PowerShell terminal to check the IP of the corresponding WSL virtual NIC (take the IPv4 address under the Ethernet adapter vEthernet (WSL (Hyper-V firewall))).

wsl --install -d Ubuntu

The 172.20.192.1 in the first line of the container start command below is the IP of the WSL virtual NIC found with ipconfig

In PowerShell:

wslc run -d --name qflowgpu -e SERVERIP=172.20.192.1 `
  -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 -e SERVERIP=172.20.192.1 ^
  -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.

wslc ps

wslc ps -a

wslc start qflowgpu

wslc stop qflowgpu

wslc rm qflowgpu

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.

Note: when installing the GPU version of PWstudio on Windows, after logging into the container, if you submit jobs from the command line inside the container, you can use the slurm.sh script file in example01 to submit jobs, but you need to make the following two changes:

1. Change the IP in the script to the IP of the WSL virtual NIC found with ipconfig — that is, in the last job-submission command of the script, change 172.20.192.1 to your own WSL virtual NIC IP:

mpirun -np $SLURM_NPROCS PWmat -host 172.20.192.1 50001 | tee output

2. You also need to delete or comment out the following two commands in the script:

#SBATCH --gres=gpu:2
#SBATCH --gpus-per-task=1