[Bug] Unsloth Studio installation fails on Windows 11 with scoop

[JackieJK]

⚡wo ❯❯ irm https://unsloth.ai/install.ps1 | iex

  🦥 Unsloth Studio Installer (Windows)
  ────────────────────────────────────────────────────

  python         Python 3.12 already installed
                 removing existing environment for fresh install...
  venv           creating Python 3.12 virtual environment
                 C:\Users\wo\.unsloth\studio\unsloth_studio
  gpu            NVIDIA GPU detected
                 installing PyTorch (https://download.pytorch.org/whl/cu130)...
                 installing unsloth (this may take a few minutes)...
  setup          running unsloth studio setup...
Note: 'unsloth studio setup' is deprecated. Use 'unsloth studio update' or re-run install.sh.

  🦥 Unsloth Studio Setup
  ────────────────────────────────────────────────────
  gpu            NVIDIA GPU detected
[OK] Windows Long Paths enabled
  git            git version 2.49.0.windows.1
  cmake          cmake version 4.3.1
  vs             Visual Studio 17 2022 (filesystem (BuildTools))
   cl.exe: C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Tools\MSVC\14.44.35207\bin\Hostx64\x64\cl.exe
   Driver supports up to CUDA 13.2
   GPU Compute Capability = 8.9 (sm_89)
   [OK] Using existing CUDA Toolkit at CUDA_PATH (nvcc: C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v13.1\bin\nvcc.exe)
   Persisted CUDA_PATH=C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v13.1 to user environment
   Set CUDA_PATH_V13_1 (cleared other CUDA_PATH_V* vars)
  cuda           C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v13.1\bin\nvcc.exe
   CUDA_PATH      = C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v13.1
   CudaToolkitDir = C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v13.1\
[OK] Node v25.8.0 and npm 11.11.1 already meet requirements.
  node           v25.8.0 | npm 11.11.1
[OK] bun already installed (1.3.5)

--- System prerequisites ready ---

  frontend       up to date
Installing OXC validator runtime...
[OK] OXC validator runtime installed

Setting up Python environment...
[OK] Using D:\scoop\Scoop\shims\python3.exe (Python 3.12.10)
   [INFO] Stale venv detected (torch cpu != required cu130) -- rebuilding...
   [ERROR] Could not remove stale venv: 对路径“python.exe”的访问被拒绝。
           Close any running Studio/Python processes and re-run setup.
[ERROR] unsloth studio setup failed (exit code 1)

[rolandtannous]

did you check if you had running python processes that are file locked?
could you also please explain your setup. thank you

[htw2ai]

Remove the PYTHONPATH environment variable

[JackieJK]

did you check if you had running python processes that are file locked? could you also please explain your setup. thank you

是的，我检查过没有python进程，也没有其他进程会锁定我的python相关文件。
我的环境是windows 11 + scoop + python3.12

Yes, I checked and there are no Python processes, nor any other processes that would lock my Python-related files.
My environment is Windows 11 + Scoop + Python 3.12.

[JackieJK]

Remove the PYTHONPATH environment variable

I don't understand what you mean? I installed Python via scoop install python312 && scoop reset python312

[JyothishArumugam]

Root Cause Found + Full Workaround

I hit the exact same error on Windows 11 with Python 3.13.5 and CUDA 12.4.
After extensive debugging, I identified four distinct bugs causing this failure.

---

Root Cause 1: uv strips the CUDA suffix from torch when resolving unsloth

The installer installs torch+cu124 in phase 1, but when unsloth is resolved
in the same uv pip install call, uv's solver replaces it with torch==2.10.0
(CPU-only, no CUDA suffix). This is why setup.ps1 always sees "torch cpu"
regardless of GPU.

Fix: Install torch and unsloth in separate uv pip install calls,
and pin torch before installing unsloth.

Root Cause 2: Remove-Item fails on Windows due to file handle locking on .exe files

setup.ps1 uses PowerShell's Remove-Item to delete the stale venv. On Windows,
.exe files inside a freshly created venv retain residual handles even after the
creating process exits. Remove-Item fails with "Access Denied" while
cmd /c rd /s /q works reliably.

Fix: Replace Remove-Item -Recurse -Force $VenvDir in setup.ps1 with:

cmd /c "icacls $VenvDir /grant *S-1-1-0:(F) /T /C" | Out-Null
cmd /c "rd /s /q $VenvDir" | Out-Null

---

Root Cause 3: xformers has no Python 3.13 wheels, making unsloth unsatisfiable

The installer auto-installs Python 3.13 but xformers only has wheels up to cp312:

Fix: Use --no-deps for unsloth on Python 3.13, or pin Python 3.12 in the installer.

---

Root Cause 4: no-deps skips installation we would be left with packages missing.

After manually fixing the venv, launching unsloth studio crashes with missing modules:

• structlog
• diceware
• matplotlib
• nest_asyncio
• PyJWT (wrong package jwt is installed — it has no .encode() attribute)

---

Working Workaround

Also a complete solution adhering the code structure is submitted in the PR (#4877)

# 1. Grant permissions and wipe stale venv
cmd /c "icacls C:\Users\$env:USERNAME\.unsloth /grant *S-1-1-0:(F) /T /C"
cmd /c "rd /s /q C:\Users\$env:USERNAME\.unsloth"

# 2. Run installer (will fail at setup - expected)
irm https://unsloth.ai/install.ps1 | iex

# 3. Install CUDA torch AFTER unsloth (uv strips it otherwise)
uv pip install --python "$env:USERPROFILE\.unsloth\studio\unsloth_studio\Scripts\python.exe" `
    torch==2.6.0+cu124 torchvision==0.21.0+cu124 torchaudio==2.6.0+cu124 `
    --index-url https://download.pytorch.org/whl/cu124

# 4. Install unsloth with --no-deps (xformers has no Python 3.13 wheels)
uv pip install --python "$env:USERPROFILE\.unsloth\studio\unsloth_studio\Scripts\python.exe" `
    unsloth unsloth-zoo --no-deps

# 5. Install all missing runtime deps including correct JWT package
uv pip install --python "$env:USERPROFILE\.unsloth\studio\unsloth_studio\Scripts\python.exe" `
    transformers trl peft accelerate bitsandbytes huggingface-hub `
    typer rich datasets safetensors sentencepiece pydantic `
    structlog fastapi starlette uvicorn nest-asyncio httpx websockets `
    python-multipart aiofiles psutil pydantic-settings watchfiles `
    matplotlib scipy scikit-learn plotly pandas pillow `
    python-dotenv pyyaml toml anyio diceware PyJWT

# 6. Run setup manually
$env:SKIP_STUDIO_BASE = "1"
& "$env:USERPROFILE\.unsloth\studio\unsloth_studio\Scripts\unsloth.exe" studio setup

# 7. Launch
& "$env:USERPROFILE\.unsloth\studio\unsloth_studio\Scripts\unsloth.exe" studio -H 0.0.0.0 -p 8888

This also affects users with Scoop Python, PyManager, and likely any
non-standard Python manager — the common thread is uv stripping the CUDA
torch build and Remove-Item failing on Windows file locks.

Verified working on: Windows 11, Python 3.13.5, CUDA 12.4, RTX 3060 Laptop GPU.

[rolandtannous]

@JyothishArumugam this diagnosis is not accurate. The issue here is only scoop specific. Where no scoop is used, it's confirmed to work on windows via user testing and internal testing. Your specific issue is different . i think its a cuda mismatch on windows that a lot of users on windows had and we fixed as follows: You need to make sure that the cuda version shown by nvcc --version matches the CUDA version shown by nvidia-smi on windows.
changing the way we install the package in the manner done in your fix will actually break the package. The install sequence, flags used, are intentional.

[JyothishArumugam]

@rolandtannous I've verified my environment (screenshot attached), and both nvcc and nvidia-smi are aligned on CUDA 12.4. The issue I'm seeing isn't a version mismatch, but the uv resolver stripping the +cu124 suffix during the main install, which leads to the venv-rebuild loop. How can we ensure the CUDA suffix is preserved while staying within the intentional install sequence?

[rolandtannous]

@JyothishArumugam ping me on our discord server https://discord.com/invite/unsloth on the help channel and we'll troubleshoot it more thoroughly for your case. My username there is Roland

[zhengyuxi1]

我遇到和楼主一样的问题，使用以下步骤成功安装了

1. 用 icacls + rd 清除旧环境
2. 运行 install.ps1（预期失败）
3. 单独安装 torch==2.5.1+cu121（你的驱动不支持 cu124）
4. 用 --no-deps 安装 unsloth unsloth-zoo（防止 torch 被替换）
5. 补装所有运行时依赖（也用 --no-deps）
6. 直接启动，跳过 setup 步骤

[qwertie]

@rolandtannous I have the same error (after removing C:\Python314 from PATH, whose presence also prevented installation, and restarting my PC):

                 setting up Python environment...
                 Using C:\Users\qwert\AppData\Local\Programs\Python\Python313\python.exe (Python 3.13.13)
                 Stale venv detected (torch cpu != required cu124) -- rebuilding...
   [ERROR] Could not remove stale venv: Access to the path 'python.exe' is denied.
           Close any running Studio/Python processes and re-run setup.
[ERROR] unsloth studio setup failed (exit code 1)

You suggested comparing versions? They are both 12.0 for me:

PS C:\Users\qwert> nvcc --version
nvcc: NVIDIA (R) Cuda compiler driver
Copyright (c) 2005-2023 NVIDIA Corporation
Built on Fri_Jan__6_19:04:39_Pacific_Standard_Time_2023
Cuda compilation tools, release 12.0, V12.0.140
Build cuda_12.0.r12.0/compiler.32267302_0

PS C:\Users\qwert> nvidia-smi
Thu Apr 30 07:11:29 2026
+-----------------------------------------------------------------------------+
| NVIDIA-SMI 528.79       Driver Version: 528.79       CUDA Version: 12.0     |
|-------------------------------+----------------------+----------------------+
| GPU  Name            TCC/WDDM | Bus-Id        Disp.A | Volatile Uncorr. ECC |
| Fan  Temp  Perf  Pwr:Usage/Cap|         Memory-Usage | GPU-Util  Compute M. |
|                               |                      |               MIG M. |
|===============================+======================+======================|
|   0  NVIDIA RTX A200... WDDM  | 00000000:01:00.0 Off |                  N/A |
| N/A   47C    P0     9W /  40W |      0MiB /  8192MiB |      0%      Default |
|                               |                      |                  N/A |
+-------------------------------+----------------------+----------------------+

+-----------------------------------------------------------------------------+
| Processes:                                                                  |
|  GPU   GI   CI        PID   Type   Process name                  GPU Memory |
|        ID   ID                                                   Usage      |
|=============================================================================|
|  No running processes found                                                 |
+-----------------------------------------------------------------------------+

[huainian6911]

I have a same error with uv:

PS E:\projects\unsloth_project> irm https://unsloth.ai/install.ps1 | iex

  🦥 Unsloth Studio Installer (Windows)
  ────────────────────────────────────────────────────

  winget         available
  python         Python 3.13 already installed
  venv           creating Python 3.13 virtual environment
                 C:\Users\53106\.unsloth\studio\unsloth_studio
  gpu            NVIDIA GPU detected
                 installing PyTorch (https://download.pytorch.org/whl/cu130)...
                 installing unsloth (this may take a few minutes)...
                 PyTorch flavor mismatch (installed cpu, need cu130) -- reinstalling correct build...

  [WARN] PyTorch is CPU-only but a cu130 GPU build was expected for this machine.
  [WARN] Training and GPU inference will run on CPU until this is fixed.
  [WARN] Re-run this installer, or reinstall the GPU build manually for your GPU.
  setup          running unsloth studio setup...

  🦥 Unsloth Studio Setup
  ────────────────────────────────────────────────────
  gpu            NVIDIA GPU detected
  long paths     enabled
  git            git version 2.54.0.windows.1
  vcredist       present
  cmake          cmake version 4.3.3
  vs             Visual Studio 17 2022 (filesystem (BuildTools)) (only used if a source build is needed)
                 cl.exe: C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Tools\MSVC\14.44.
35207\bin\Hostx64\x64\cl.exe
                 Node v24.11.0 and npm 11.6.2 already meet requirements (system).
                 Python 3.13.14

  system         prerequisites ready

  frontend       up to date
  node           v24.11.0 | npm 11.6.2 (system)
                 installing OXC validator runtime...
  oxc runtime    installed

                 setting up Python environment...
                 Python found: C:\Users\53106\.unsloth\studio\unsloth_studio\Scripts\python.exe
                 Stale venv detected (torch cpu != required cu130).
   [ERROR] The existing Studio environment needs repair.
           Re-run install.ps1 so it can replace the environment safely with rollback.
[ERROR] unsloth studio setup failed (exit code 1)