在 Windows 上安装 Unsloth

查看在有或没有 WSL 的情况下如何在 Windows 上安装 Unsloth。

对于 Windows， pip install unsloth 现在可行，但你必须事先安装 Pytorch。

方法 #1 - Docker：

对于 Windows 用户，Docker 可能是开始使用 Unsloth 最简单的方式，因为无需设置或处理依赖问题。 unsloth/unsloth 是 Unsloth 的唯一 Docker 镜像。对于 Blackwell 和 50 系列 GPU，使用相同的镜像即可——不需要单独的镜像。

有关安装说明，请参阅我们的 Docker 指南，否则这里有一个快速入门指南：

安装 Docker 和 NVIDIA Container Toolkit。

通过以下方式安装 Docker Linux 或 Desktop （其他）。然后安装 NVIDIA Container Toolkit:

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}

运行容器。

unsloth/unsloth 是 Unsloth 的唯一 Docker 镜像。

docker run -d -e JUPYTER_PASSWORD="mypassword" \
  -p 8888:8888 -p 2222:22 \
  -v $(pwd)/work:/workspace/work \
  --gpus all \
  unsloth/unsloth

访问 Jupyter Lab

前往 http://localhost:8888 并打开 Unsloth。访问 unsloth-notebooks 选项卡以查看 Unsloth 笔记本。

开始使用 Unsloth 训练

如果你是新手，请按照我们的逐步微调指南, 强化学习指南或直接保存/复制我们任何预制的笔记本.

Docker 问题 - GPU 未被发现？

尝试通过 WSL 来做 Windows

方法 #2 - WSL：

安装 WSL

打开命令提示符或终端，安装 Ubuntu。如有提示请设置密码。

wsl.exe --install Ubuntu-24.04
wsl.exe -d Ubuntu-24.04

如果你没有执行（1），也就是说你已经安装了 WSL，通过输入以下命令进入 WSL wsl 并在命令提示符中按回车

wsl

安装 Python

sudo apt update
sudo apt install python3 python3-full python3-pip python3-venv -y

安装 PyTorch

pip install torch torchvision --force-reinstall --index-url https://download.pytorch.org/whl/cu130

如果遇到权限问题，请使用 –break-system-packages 因此 pip install torch torchvision --force-reinstall --index-url https://download.pytorch.org/whl/cu130 –break-system-packages

安装 Unsloth 和 Jupyter Notebook

pip install unsloth jupyter

如果遇到权限问题，请使用 –break-system-packages 因此 pip install unsloth jupyter –break-system-packages

通过 Jupyter Notebook 启动 Unsloth

jupyter notebook

然后在其中打开我们的笔记本 Unsloth 笔记本并加载它们！你也可以转到 Colab 笔记本，选择下载 > 下载 .ipynb 并加载它们。

方法 #3 - 直接在 Windows 上：

Python 3.13 现在可与 Unsloth 一起使用！

安装 NVIDIA 显卡驱动

你应该安装显卡驱动的最新版本。在此处下载驱动： NVIDIA GPU 驱动

安装 Visual Studio C++

你需要安装 Visual Studio，并勾选安装 C++。默认情况下，Visual Studio 不会安装 C++，因此请确保选择所有 C++ 选项。还要选择 Windows 10/11 SDK 的相关选项。

在此启动安装程序： Visual Studio 社区版
在安装程序中，转到“单个组件”，并选择此处列出的所有选项：
- .NET Framework 4.8 SDK
- .NET Framework 4.7.2 目标包
- C# 和 Visual Basic Roslyn 编译器
- MSBuild
- MSVC v143 - VS 2022 C++ x64/x86 构建工具
- C++ 2022 可再发行组件更新
- 用于 Windows 的 C++ CMake 工具
- v143 构建工具的 C++/CLI 支持（最新）
- MSBuild 对 LLVM (clang-cl) 工具集的支持
- 用于 Windows 的 C++ Clang 编译器（19.1.1）
- Windows 11 SDK (10.0.22621.0)
- Windows 通用 CRT SDK
- C++ 2022 可再发行 MSMs

更简单的方法： 或者你可以打开提升权限的命令提示符或 PowerShell：

搜索 “cmd” 或 “PowerShell”，右键单击它，然后选择“以管理员身份运行”。
粘贴并运行此命令（如有必要更新 Visual Studio 路径）：

"C:\Program Files (x86)\Microsoft Visual Studio\Installer\vs_installer.exe" modify ^
--installPath "C:\Program Files\Microsoft Visual Studio\2022\Community" ^
--add Microsoft.Net.Component.4.8.SDK ^
--add Microsoft.Net.Component.4.7.2.TargetingPack ^
--add Microsoft.VisualStudio.Component.Roslyn.Compiler ^
--add Microsoft.Component.MSBuild ^
--add Microsoft.VisualStudio.Component.VC.Tools.x86.x64 ^
--add Microsoft.VisualStudio.Component.VC.Redist.14.Latest ^
--add Microsoft.VisualStudio.Component.VC.CMake.Project ^
--add Microsoft.VisualStudio.Component.VC.CLI.Support ^
--add Microsoft.VisualStudio.Component.VC.Llvm.Clang ^
--add Microsoft.VisualStudio.ComponentGroup.ClangCL ^
--add Microsoft.VisualStudio.Component.Windows11SDK.22621 ^
--add Microsoft.VisualStudio.Component.Windows10SDK.19041 ^
--add Microsoft.VisualStudio.Component.UniversalCRT.SDK ^
--add Microsoft.VisualStudio.Component.VC.Redist.MSM

安装 Python 和 CUDA 工具包

按照说明进行安装 CUDA 工具包.

然后在此处安装 Miniconda（包含 Python）： https://www.anaconda.com/docs/getting-started/miniconda/install

安装 PyTorch

您需要与您的 CUDA 驱动兼容的正确版本的 PyTorch，因此请务必仔细选择。安装 PyTorch

安装 Unsloth

打开 Conda 命令提示符或带有 Python 的终端并运行命令：

pip install "unsloth[windows] @ git+https://github.com/unslothai/unsloth.git"

如果您正在使用 GRPO 或计划使用 vLLM，目前 vLLM 不直接支持 Windows，仅通过 WSL 或 Linux 支持。

注意

要在 Windows 上直接运行 Unsloth：

从此 Windows 分支安装 Triton 并按照说明操作此处（注意该 Windows 分支要求 PyTorch >= 2.4 和 CUDA 12）
在 SFTTrainer 中，设置 dataset_num_proc=1 以避免崩溃问题：

trainer = SFTTrainer(
    dataset_num_proc=1,
    ...
)

高级/故障排除

有关 高级安装说明 或如果在安装过程中看到奇怪的错误：

安装 torch 和 triton。请访问 https://pytorch.org 安装。例如 pip install torch torchvision torchaudio triton
确认 CUDA 是否正确安装。尝试 nvcc。如果失败，您需要安装 cudatoolkit 或 CUDA 驱动程序。
安装 xformers 手动。你可以尝试安装 vllm 并查看是否 vllm 成功。检查 xformers 是否使用以下命令成功 python -m xformers.info 前往 https://github.com/facebookresearch/xformers。另一种选择是安装 flash-attn 针对 Ampere GPU。
仔细检查你的 Python、CUDA、CUDNN、 torch, triton和 xformers 是否彼此兼容。该 PyTorch 兼容性矩阵可能会有用。
最后，安装 bitsandbytes 并使用以下命令检查它 python -m bitsandbytes

方法 #3 - 在 Windows 上使用 PowerShell：

第 1 步：安装先决条件

安装 NVIDIA CUDA 工具包:
- 下载并安装适当版本的 NVIDIA CUDA 工具包 来自 CUDA 下载.
- 如果提示，安装后请重启系统。
- 注意：Unsloth 安装后不需要额外设置。
安装 Microsoft C++ 构建工具:
- 下载并安装 Microsoft Build Tools for Visual Studio 来自官方网站.
- 在安装过程中，选择 C++ 构建工具 工作负载。确保包含 MSVC 编译器工具集 已被包含。
为 C++ 编译器设置环境变量:
- 打开 系统属性 窗口（在开始菜单中搜索“环境变量”）。
- 点击 “环境变量…”.
- 在以下位置新增或更新下列项 系统变量:
  - CC： cl.exe 的路径， C++ 编译器。示例（如你的版本不同请调整）： cl.exe
    C:\Program Files\Microsoft Visual Studio\2022\BuildTools\VC\Tools\MSVC\14.34.31933\bin\Hostx64\x64\cl.exe
  - CXX：与以下相同的路径 CC.
- 点击确定以保存更改。
- 验证：打开一个新的终端并输入 cl。它应该显示版本信息。
安装 Conda
1. 下载并安装 Miniconda 来自官方网站
2. 按照网站上的安装说明进行操作
3. 要检查 conda 是否已安装，您可以使用以下命令测试它 conda 在您的 PowerShell 中

第 2 步：运行 Unsloth 安装脚本

下载 unsloth_windows.ps1 PowerShell 脚本，可通过此链接获取.
以管理员身份打开 PowerShell:
- 右键单击“开始”并选择 “Windows PowerShell（管理员）”.
导航到脚本所在位置 使用 cd:
```
cd path\to\script\folder
```

运行脚本:

powershell.exe -ExecutionPolicy Bypass -File .\unsloth_windows.ps1

第 3 步：使用 Unsloth

安装完成后激活环境：

conda activate unsloth_env

Unsloth 及其依赖项现在已准备就绪！

上一页uv, pip install & venv 下一页AMD

最后更新于1个月前

这有帮助吗？

hashtag方法 #1 - Docker：

hashtag方法 #2 - WSL：

hashtag方法 #3 - 直接在 Windows 上：

hashtag注意

hashtag高级/故障排除

hashtag方法 #3 - 在 Windows 上使用 PowerShell：

hashtag第 1 步：安装先决条件

hashtag第 2 步：运行 Unsloth 安装脚本

hashtag第 3 步：使用 Unsloth

方法 #1 - Docker：

方法 #2 - WSL：

方法 #3 - 直接在 Windows 上：

注意

高级/故障排除

方法 #3 - 在 Windows 上使用 PowerShell：

第 1 步：安装先决条件

第 2 步：运行 Unsloth 安装脚本

第 3 步：使用 Unsloth