> For the complete documentation index, see [llms.txt](https://unsloth.ai/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://unsloth.ai/docs/zh/kuai-su-kai-shi/install/windows-installation.md).
# 在 Windows 上安装 Unsloth
在 Windows 上安装 Unsloth Desktop、Unsloth Studio 或 Unsloth Core。
要在 Windows 上安装 Unsloth Desktop，请按以下步骤操作。
{% stepper %}
{% step %}
### 下载
下载适用于 Windows 的 Unsloth
{% endstep %}
{% step %}
### 安装
1. 打开 Unsloth 安装程序（`.exe` 文件）
2. 按照安装提示进行操作
3. 启动应用并等待安装完成
{% endstep %}
{% step %}
### 选择一个模型
打开“选择模型”或“模型中心”，选择一个模型和量化方式，然后下载。完成后即可开始聊天——无需设置。
{% endstep %}
{% step %}
### Unsloth 现已就绪
要开始聊天，请输入消息并按 Enter。
* **连接工具：** [Claude Code](/docs/zh/ji-chu-zhi-shi/claude-code.md), [Codex](/docs/zh/ji-chu-zhi-shi/codex.md)、网页搜索、 [MCP](/docs/zh/ji-chu-zhi-shi/mcp.md) 等更多
* **训练模型：** 微调文本、扩散、嵌入等更多模型
* **生成媒体：** 在本地创建并训练图像、视频、TTS
{% endstep %}
{% endstepper %}
### 手动安装 Unsloth
下面的部分涵盖基于网页的 **Unsloth Studio** 以及原始的基于代码的 **Unsloth Core**.
对于 **Unsloth Core** 在 Windows 上，请在下面选择 Conda、Docker 或 WSL。如果 PyTorch 已经安装， `pip install unsloth` 可能就足够了。
Conda 教程Docker 教程WSL 教程
### Unsloth Studio
下面是安装我们 Web UI 的命令 [Unsloth Studio](/docs/zh/xin/studio/install.md)
#### **PowerShell**:
```powershell
irm https://unsloth.ai/install.ps1 | iex
```
使用相同命令进行更新。
#### **Winget**:
{% tabs %}
{% tab title="安装" %}
```powershell
winget install --id UnslothAI.Unsloth -e
```
{% endtab %}
{% tab title="更新" %}
```powershell
winget upgrade --id UnslothAI.Unsloth -e
```
{% endtab %}
{% endtabs %}
#### **启动：**
{% tabs %}
{% tab title="本地启动" %}
```powershell
unsloth studio
```
{% endtab %}
{% tab title="远程访问" %}
```powershell
unsloth studio --secure
```
{% endtab %}
{% endtabs %}
有关详细的 Unsloth Studio 安装说明和要求， [查看我们的指南](/docs/zh/xin/studio/install.md).
下面是原始版本的安装说明 **Unsloth Core**:
### 方法 #1 - 通过 Conda 在 Windows 上：
{% stepper %}
{% step %}
**安装 Miniconda（或 Anaconda）**
下载 Anaconda [这里](https://www.anaconda.com/download). 我们的建议是使用 [Miniconda](https://www.anaconda.com/docs/getting-started/miniconda/install#quickstart-install-instructions). 要使用它，首先进入 PowerShell——在“开始”中搜索“Windows PowerShell”：
然后它会打开 PowerShell：
然后复制粘贴下面内容：CTRL+C，再在 PowerShell 中粘贴 CTRL+V：
{% code overflow="wrap" %}
```ps
Invoke-WebRequest -Uri "https://repo.anaconda.com/miniconda/Miniconda3-latest-Windows-x86_64.exe" -OutFile ".\miniconda.exe"
Start-Process -FilePath ".\miniconda.exe" -ArgumentList "/S" -Wait
del .\miniconda.exe
```
{% endcode %}
接受警告并点击“仍然粘贴”，然后等待。
它正在如下下载安装程序：
安装后，打开 open **Anaconda PowerShell Prompt** 要通过“开始”→搜索来使用 Miniconda：
然后你会看到：
{% endstep %}
{% step %}
**创建 conda 环境**
```bash
conda create --name unsloth_env python==3.12 -y
conda activate unsloth_env
```
**你会看到：**
{% endstep %}
{% step %}
**检查 `nvidia-smi` 以确认你有 GPU，并查看 CUDA 版本**
输入后 `nvidia-smi` 在 PowerShell 中，你应该会看到如下内容。如果你没有 `nvidia-smi` ，或者下面的内容无法弹出，你需要重新安装 [NVIDIA 驱动](https://www.nvidia.com/en-us/drivers/).
{% endstep %}
{% step %}
**安装 PyTorch**
运行时 `nvidia-smi` 你会在右上角看到：“CUDA Version: 13.0”。在 PowerShell 中通过以下方式安装 PyTorch。将 `130` 到你的 CUDA 版本——确保该 [版本存在](https://pytorch.org/) 并与你的 CUDA 驱动版本匹配。
{% code overflow="wrap" %}
```bash
pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu130
```
{% endcode %}
你会看到：
尝试在 Python 中通过以下方式运行它： `python` 在安装 PyTorch 后：
{% code overflow="wrap" %}
```python
import torch
print(torch.cuda.is_available())
A = torch.ones((10, 10), device = "cuda")
B = torch.ones((10, 10), device = "cuda")
A @ B
```
{% endcode %}
你应该会看到一个全是 10 的矩阵。同时确认第一个返回 True。
{% endstep %}
{% step %}
**安装 Unsloth（仅当 PyTorch 正常工作时！）**
{% hint style="danger" %}
**确认 PyTorch 能正常运行——如果不能，说明 PyTorch 出问题了，这意味着你的 Windows 机器可能不幸需要重新安装 CUDA 驱动。**
{% endhint %}
在 PowerShell 中（通过以下方式退出 Python 后 `exit()` ，执行并等待：
```bash
pip install unsloth
```
{% endstep %}
{% step %}
**验证 Unsloth 是否可用**
现在使用其中任意脚本 [Unsloth 笔记本](/docs/zh/kuai-su-kai-shi/unsloth-notebooks.md) （保存为 .py 文件），或者使用下面的基础脚本：
{% code expandable="true" %}
```python
from unsloth import FastLanguageModel, FastModel
import torch
from trl import SFTTrainer, SFTConfig
from datasets import load_dataset
max_seq_length = 512
url = "https://huggingface.co/datasets/laion/OIG/resolve/main/unified_chip2.jsonl"
dataset = load_dataset("json", data_files = {"train" : url}, split = "train")
model, tokenizer = FastLanguageModel.from_pretrained(
model_name = "unsloth/gemma-3-270m-it",
max_seq_length = max_seq_length, # 选择任意值以适应长上下文！
load_in_4bit = True, # 4 位量化。False = 16 位 LoRA。
load_in_8bit = False, # 8 位量化
load_in_16bit = False, # 16 位 LoRA
full_finetuning = False, # 用于完整微调。
trust_remote_code = False, # 启用以支持新模型
# token = "hf_...", # 如果使用受限模型，请使用一个
)
# 执行模型补丁并添加快速 LoRA 权重
model = FastLanguageModel.get_peft_model(
model,
r = 16,
target_modules = ["q_proj", "k_proj", "v_proj", "o_proj",
"gate_proj", "up_proj", "down_proj",],
lora_alpha = 16,
lora_dropout = 0, # 支持任意值，但 = 0 时已优化
bias = "none", # 支持任意值，但 = "none" 时已优化
# [新] “unsloth” 可减少 30% 显存占用，可容纳大 2 倍的批次大小！
use_gradient_checkpointing = "unsloth", # 超长上下文时可设置为 True 或 "unsloth"
random_state = 3407,
max_seq_length = max_seq_length,
use_rslora = False, # 我们支持秩稳定 LoRA
loftq_config = None, # 以及 LoftQ
)
trainer = SFTTrainer(
model = model,
train_dataset = dataset,
tokenizer = tokenizer,
args = SFTConfig(
max_seq_length = max_seq_length,
per_device_train_batch_size = 2,
gradient_accumulation_steps = 4,
warmup_steps = 10,
max_steps = 60,
logging_steps = 1,
output_dir = "outputs",
optim = "adamw_8bit",
seed = 3407,
dataset_num_proc = 1,
),
)
trainer.train()
```
{% endcode %}
你应该会看到：
```bash
🦥 Unsloth：将修补你的电脑，以启用快 2 倍的免费微调。
🦥 Unsloth Zoo 现在将修补一切，以加快训练！
==((====))== Unsloth 2026.1.4：快速 Gemma3 补丁。Transformers: 4.57.6。
\\ /| NVIDIA GeForce RTX 3060。GPU 数量 = 1。最大内存：12.0 GB。平台：Windows。
O^O/ \_/ \ Torch：2.10.0+cu130。CUDA：8.6。CUDA 工具包：13.0。Triton：3.6.0
\ / Bfloat16 = TRUE。FA [Xformers = 0.0.34。FA2 = False]
"-____-" 免费许可证: http://github.com/unslothai/unsloth
Unsloth：已启用快速下载——忽略红色的下载进度条！
Unsloth：Gemma3 不支持 SDPA——切换到快速 eager。
Unsloth：使 `model.base_model.model.model` 需要梯度
Unsloth：正在对 ["text"] 进行分词 (num_proc=1)： 0%| | 0/210289 [00:00
{% endstep %}
{% endstepper %}
### 方法 #2 - Docker：
对于 Windows 用户来说，Docker 可能是开始使用 Unsloth 的最简单方式，因为无需设置，也没有依赖问题。 [**`unsloth/unsloth`**](https://hub.docker.com/r/unsloth/unsloth) 是 Unsloth 唯一的 Docker 镜像。对于 [Blackwell](/docs/zh/bo-ke/fine-tuning-llms-with-blackwell-rtx-50-series-and-unsloth.md) 和 50 系列 GPU，请使用同一个镜像——无需单独镜像。
有关安装说明，请参阅我们的 [Docker 指南](/docs/zh/bo-ke/how-to-fine-tune-llms-with-unsloth-and-docker.md)，否则这里有一个快速入门指南：
{% stepper %}
{% step %}
**安装 Docker 和 NVIDIA Container Toolkit。**
通过以下方式安装 Docker [Linux](https://docs.docker.com/engine/install/) 或者 [桌面版](https://docs.docker.com/desktop/) （其他）。然后安装 [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html#installation):
```bash
export NVIDIA_CONTAINER_TOOLKIT_VERSION=1.17.8-1
sudo apt-get update && sudo apt-get install -y \\
nvidia-container-toolkit=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \\
nvidia-container-toolkit-base=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \\
libnvidia-container-tools=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \\
libnvidia-container1=${NVIDIA_CONTAINER_TOOLKIT_VERSION}
```
{% endstep %}
{% step %}
**运行容器。**
[**`unsloth/unsloth`**](https://hub.docker.com/r/unsloth/unsloth) 是 Unsloth 唯一的 Docker 镜像。
```bash
docker run -d -e JUPYTER_PASSWORD="mypassword" \\
-p 8888:8888 -p 2222:22 \\
-v $(pwd)/work:/workspace/work \\
--gpus all \\
unsloth/unsloth
```
{% endstep %}
{% step %}
**访问 Jupyter Lab**
前往 [http://localhost:8888](http://localhost:8888/) 并打开 Unsloth。访问 `unsloth-notebooks` 选项卡以查看 Unsloth 笔记本。
{% endstep %}
{% step %}
**开始使用 Unsloth 训练**
如果你是新手，请按照我们的分步 [微调指南](/docs/zh/kuai-su-kai-shi/fine-tuning-llms-guide.md), [RL 指南](/docs/zh/kuai-su-kai-shi/reinforcement-learning-rl-guide.md) 或者只需保存/复制我们预制的任意 [笔记本](/docs/zh/kuai-su-kai-shi/unsloth-notebooks.md).
{% endstep %}
{% step %}
**Docker 问题——未检测到 GPU？**
试试通过以下方式使用 WSL [#method-2-wsl](#method-2-wsl "mention")
{% endstep %}
{% endstepper %}
### 方法 #3 - WSL：
{% stepper %}
{% step %}
**安装 WSL**
打开命令提示符或终端，并安装 Ubuntu。如果提示，请设置密码。
```bash
wsl.exe --install Ubuntu-24.04
wsl.exe -d Ubuntu-24.04
```
{% endstep %}
{% step %} **如果你没有执行 (1)，也就是你已经安装了 WSL****，通过输入以下命令进入 WSL `wsl` 并在命令提示符中按 ENTER**
```bash
wsl
```
{% endstep %}
{% step %}
**安装 Python**
{% code overflow="wrap" %}
```bash
sudo apt update
sudo apt install python3 python3-full python3-pip python3-venv -y
```
{% endcode %}
{% endstep %}
{% step %}
**安装 PyTorch**
{% code overflow="wrap" %}
```bash
pip install torch torchvision --force-reinstall --index-url https://download.pytorch.org/whl/cu130
```
{% endcode %}
如果遇到权限问题，请使用 `–break-system-packages` 因此 `pip install torch torchvision --force-reinstall --index-url https://download.pytorch.org/whl/cu130 –break-system-packages`
{% endstep %}
{% step %}
**安装 Unsloth 和 Jupyter Notebook**
{% code overflow="wrap" %}
```bash
pip install unsloth jupyter
```
{% endcode %}
如果遇到权限问题，请使用 `–-break-system-packages` 因此 `pip install unsloth jupyter –-break-system-packages`
{% endstep %}
{% step %}
**通过 Jupyter Notebook 启动 Unsloth**
{% code overflow="wrap" %}
```bash
jupyter notebook
```
{% endcode %}
然后在其中打开我们的笔记本 [Unsloth 笔记本](/docs/zh/kuai-su-kai-shi/unsloth-notebooks.md)并将它们加载进来！你也可以前往 Colab 笔记本，下载 > 下载 .ipynb，然后加载它们。
{% endstep %}
{% endstepper %}
{% hint style="warning" %}
如果你正在使用 GRPO 或计划使用 vLLM，目前 vLLM 不直接支持 Windows，只能通过 WSL 或 Linux。
{% endhint %}
### **故障排除 /** 高级
对于 **高级安装说明** 或者如果你在安装期间看到奇怪的错误：
1. 安装 `torch` 和 `triton`. 前往 安装它。例如 `pip install torch torchvision torchaudio triton`
2. 确认 CUDA 是否安装正确。试试 `nvcc`. 如果失败，你需要安装 `cudatoolkit` 或 CUDA 驱动。
3. 如果使用 Intel GPU，你需要遵循我们的 [Intel Windows 指南](/docs/zh/kuai-su-kai-shi/install/intel.md#windows-only-runtime-configurations)
4. 安装 `xformers` 手动安装。你可以尝试安装 `vLLM` 并查看是否 `vLLM` 成功。检查是否 `xformers` 已通过 `python -m xformers.info` 前往 `flash-attn` 用于 Ampere GPU。
5. 再次检查你的 Python、CUDA、CUDNN、 `torch`, `triton`、和 `xformers` 彼此是否兼容。 [PyTorch 兼容性矩阵](https://github.com/pytorch/pytorch/blob/main/RELEASE.md#release-compatibility-matrix) 可能会有帮助。
6. 最后，安装 `bitsandbytes` 并用以下方式检查它 `python -m bitsandbytes`
7. 如果 Unsloth 没有检测到或使用你的 GPU，并且你在 Windows 上使用我们的 Docker 容器，那么你的 CUDA 工具包版本 `nvcc --version` 应与主机上 nvidia-smi 显示的 CUDA 版本匹配。Windows 上 Docker 容器的 GPU 支持并不是自动的。 [你需要遵循 Docker 的指南](https://docs.docker.com/desktop/features/gpu/).
## 卸载
#### Unsloth Desktop
1. 如果 Unsloth 正在运行，请将其关闭。
2. 打开 **设置** 在 Windows 中。
3. 前往 **应用** → **已安装的应用**.
4. 找到 **Unsloth**，选择三点菜单，然后选择 **卸载**.
5. 按照提示删除该应用。
卸载 Unsloth Desktop 不会删除已下载的模型或你的文件。
#### Unsloth Studio（手动安装）
完全移除 Unsloth Studio 的推荐方式是使用适用于你操作系统的卸载脚本。它会停止任何正在运行的服务器，移除应用、CLI 命令、启动器数据、快捷方式以及平台特定条目（macOS `.app` 捆绑包 + Launch Services；Windows 开始菜单 + 注册表 + PATH）：
```ps1
irm https://raw.githubusercontent.com/unslothai/unsloth/main/scripts/uninstall.ps1 | iex
```
#### 手动卸载
如果你只想删除特定部分：
**1. 仅删除应用** （保留历史记录、聊天、检查点和导出内容）：
* `Remove-Item -Recurse -Force "$HOME\.unsloth\studio\unsloth_studio"`
**2. 完全删除 Unsloth** （保留其他 Unsloth 工具）：
* `Remove-Item -Recurse -Force "$HOME\.unsloth\studio"`
**3. 删除所有与 Unsloth 相关的内容：**
* `Remove-Item -Recurse -Force "$HOME\.unsloth"`
{% hint style="warning" %}
注意：第 3 步会删除历史记录、聊天、模型检查点和导出内容中的所有内容。此操作无法撤销。
{% endhint %}
**4. 删除快捷方式和符号链接：**
```shellscript
Remove-Item -Force "$HOME\Desktop\Unsloth Studio.lnk"
Remove-Item -Force "$env:APPDATA\Microsoft\Windows\Start Menu\Programs\Unsloth Studio.lnk"
```
**5. 删除 CLI 命令：**
* **Windows（PowerShell）：** 安装程序已将虚拟环境的 `Scripts` 目录添加到你的用户 PATH 中。要移除它，请打开 设置 → 系统 → 关于 → 高级系统设置 → 环境变量，找到 `Path` 在“用户变量”下，并删除指向以下位置的条目 `.unsloth\studio\...\Scripts`.
{% hint style="info" %}
注意：第 1-5 步不会影响你已下载的 HF 模型文件。如果你想释放那部分空间，请参阅下面的删除缓存的 HF 模型文件。
{% endhint %}
### **删除缓存的 HF 模型文件**
你可以通过模型搜索中的垃圾桶图标删除旧模型文件，或者从默认的 Hugging Face 缓存目录中删除相关的缓存模型文件夹。默认情况下，Hugging Face 使用 `~/.cache/huggingface/hub/` 在 macOS/Linux/WSL 上使用 `C:\Users\\.cache\huggingface\hub\` 在 Windows 上使用。
* **Windows：** `%USERPROFILE%\.cache\huggingface\hub\`
如果 `HF_HUB_CACHE` 或者 `HF_HOME` 已设置，则改用该位置。在 Linux 和 WSL 上， `XDG_CACHE_HOME` 也可以更改默认缓存根目录。
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://unsloth.ai/docs/zh/kuai-su-kai-shi/install/windows-installation.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.