====== Installing the PWstudio GPU version on Windows 11 (WSL2) ======

Applies to: Windows 11\\

<wrap important>
Before you start, we strongly recommend reading [[en:pwstudio:readme|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.
</wrap>

----

===== 1. My system =====

First, check your Windows version number. Open ''cmd'' or ''powershell'' (type "powershell" into the Start menu search box to find it), and run:
<code powershell>
winver            # The version I'm using is: Windows 11 25H2 (26200.8655)
or
systeminfo | findstr "OS"
</code>

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.

===== 2. Install WSL =====

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

  - Open PowerShell as administrator: search for ''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**)

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

<code powershell>
wsl --update --pre-release
</code>

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.

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

<code powershell>
wsl --shutdown
</code>

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.

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

<code powershell>
wslc --version
</code>

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

===== 3. Verify container functionality =====

The commands below are also run in PowerShell, to verify that the container feature is working correctly.

Verify CPU container functionality:

<code powershell>
wslc run --rm swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/hello-world:latest
</code>

If you see text starting with "Hello from Docker!", basic container functionality is working.

Verify GPU container functionality:

<code powershell>
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
</code>

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.

===== 4. Install the server.py service on the host machine =====

Installation instructions: click the link, [[en:pwstudio:server|Installing the server.py service on Linux]], and follow the guide to set up the license service before moving to the next step.

===== 5. Import the image =====

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

<code bash>
wslc pull ccr.ccs.tencentyun.com/lxkt/qflowgpu:latest
</code>

===== 6. Start the container =====

In PowerShell:

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

In cmd:

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

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.

<wrap tip>
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.
</wrap>

===== 7. Troubleshooting =====

==== 7.1 Error code: HCS_E_SERVICE_NOT_AVAILABLE ====

If you see an error like this when running the verification command:

<code powershell>
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
</code>

<wrap em>Fix</wrap>

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):
<code powershell>
Enable-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform -All
</code>

<wrap notice>Be sure to restart your computer</wrap> for the change to take effect. Once it's back up, reopen PowerShell and try the verification command from chapter 3 again.

==== 7.2 GPU access blocked by the operating system ====

If you see an error like this when running the GPU verification command:

<code powershell>
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
</code>

<wrap em>🔍 Why this happens</wrap>

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.

<wrap em>🔧 Fix</wrap>

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)

> [[https://www.nvidia.com/drivers|Go to the NVIDIA website]] → select the correct GPU model → <wrap em>Key step:</wrap> in the Operating System drop-down, choose Windows 11 or Windows 10
>
> <wrap hi>Choose the Game Ready driver</wrap> (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.

===== Logging in and using PWstudio =====

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: [[en:pwstudio:quickstart_gpu|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 [[en:pwstudio:mobaxterm|the MobaXterm beginner tutorial]] first.

~~DISCUSSION:off~~