在 Windows + WSL2 中安装 LLaMA-Factory

适用场景：Windows 10/11、WSL2 Ubuntu、NVIDIA 显卡、使用uv管理 Python 环境、通过 WebUI 运行 LLaMA-Factory。
本文所有 Linux 命令都在WSL 的 Ubuntu 终端中执行；只有明确标注“Windows PowerShell”的命令才在 Windows 中执行。

0. 开始前先看

本文采用下面的目录结构：

/home/<你的用户名>/LlamaFactory # 程序和项目虚拟环境 /home/<你的用户名>/models/huggingface # Hugging Face 缓存

例如，用户名是wwei时，对应路径为：

/home/wwei/LlamaFactory /home/wwei/models/huggingface

建议把程序和常用模型放在 WSL 的 Linux 文件系统中，不要把项目放在/mnt/c/...。Linux 文件系统通常更适合训练时的大量文件读写。

WSL 的 Linux 文件系统默认存放在虚拟磁盘中，因此物理上通常仍占用 Windows 的 C 盘空间。若 C 盘空间不足，应考虑迁移 WSL 发行版或把不常用模型放到其他磁盘；直接使用/mnt/d/...虽然省 C 盘空间，但文件访问性能可能低于 Linux 文件系统。

本文曾验证过的机器配置为：

GPU：NVIDIA GeForce RTX 4060 Laptop GPU（8 GB） Python：3.11 PyTorch：2.6.0 + CUDA 12.6 wheel

软件版本会更新。全新安装时应同时参考：

• LLaMA-Factory 官方仓库
• PyTorch 官方安装选择器
• uv 官方安装说明
• NVIDIA CUDA on WSL 指南

一、安装并检查 WSL2

1. 首次安装 WSL

仅首次安装时，用管理员身份打开 Windows PowerShell：

wsl--install-d Ubuntu

如果系统提示重启，请先重启 Windows。第一次打开 Ubuntu 时，按提示创建 Linux 用户名和密码。

更新 WSL：

wsl--update

检查 Ubuntu 是否运行在 WSL2：

wsl-l-v

应看到 Ubuntu 的VERSION为2。如果显示为1，执行：

wsl--set-versionUbuntu 2

如果发行版名称不是Ubuntu，请把命令中的Ubuntu换成wsl -l -v显示的实际名称。

2. 日常打开 WSL

安装完成后，日常使用不需要管理员权限。任选一种方式：

• 开始菜单中打开 Ubuntu；
• 在 Windows Terminal 中打开 Ubuntu；
• 在普通 PowerShell 中执行wsl ~。

后续章节默认都在 Ubuntu 终端中操作。

二、配置并验证 NVIDIA GPU

1. 在 Windows 中安装显卡驱动

从 NVIDIA 官方渠道安装或更新 Windows 显卡驱动。安装完成后，可在 Windows PowerShell 中检查：

nvidia-smi

2. 在 WSL 中检查显卡

打开 Ubuntu，执行：

nvidia-smi

再查看简要信息：

nvidia-smi --query-gpu=name,memory.total,driver_version--format=csv,noheader

只要能看到显卡型号、显存和驱动版本，就说明 WSL 已识别显卡。

重要：不要在 WSL 中安装 Linux NVIDIA 显示驱动。WSL2 直接使用 Windows 主机上的 NVIDIA 驱动。不要执行sudo apt install nvidia-driver-*，也不要安装会附带 Linux 驱动的cuda、cuda-12-x或cuda-drivers元包。

通常使用 PyTorch 官方预编译 wheel 时，也不需要另装完整 CUDA Toolkit。只有编译 CUDA 扩展等特殊场景才需要 Toolkit；届时应选择 WSL 专用安装方式，并只安装cuda-toolkit-12-x一类不覆盖驱动的工具包。

另外，nvidia-smi顶部显示的CUDA Version代表当前驱动可支持的最高 CUDA 版本，不等于 Ubuntu 中已经安装了同版本 CUDA Toolkit。

三、更新 Ubuntu 并安装基础工具

在 WSL 的 Ubuntu 终端中执行：

sudoaptupdatesudoaptupgrade-ysudoaptinstall-ygitcurlbuild-essential

检查：

git--versioncurl--version

四、安装 uv

使用 uv 官方安装脚本：

curl-LsSfhttps://astral.sh/uv/install.sh|sh

让当前终端立即识别uv：

source"$HOME/.local/bin/env"2>/dev/null||exportPATH="$HOME/.local/bin:$PATH"

检查安装结果：

uv--version

如果仍提示uv: command not found，关闭 Ubuntu 终端并重新打开，再执行uv --version。

以后更新 uv：

uv self update

五、下载 LLaMA-Factory

回到 Linux 主目录，再克隆仓库：

cd~gitclone--depth1https://github.com/hiyouga/LlamaFactory.gitcd~/LlamaFactory

检查当前路径：

pwd

输出应类似：

/home/wwei/LlamaFactory

如果提示目标目录已经存在：

fatal: destination path 'LlamaFactory' already exists

不要重复克隆，直接进入已有目录：

cd~/LlamaFactory

六、创建项目专属 Python 环境

确认当前目录是~/LlamaFactory，然后创建 Python 3.11 环境：

cd~/LlamaFactory uv venv--python3.11source.venv/bin/activate

uv会在需要时自动下载合适的 Python 版本。

检查：

python--versionwhichpython

理想输出类似：

Python 3.11.x /home/wwei/LlamaFactory/.venv/bin/python

关键是which python必须指向~/LlamaFactory/.venv/bin/python。终端前面的环境名称可能显示为(.venv)、(LlamaFactory)或其他名称，不影响使用。

不要在主目录~中直接执行uv venv，否则会误创建~/.venv，不利于区分不同项目。

七、安装 GPU 版 PyTorch

方案 A：复现本文已验证的环境

对于已验证的 RTX 4060 + Python 3.11 环境，可安装 LLaMA-Factory 官方推荐的 PyTorch 2.6.0 组合：

cd~/LlamaFactorysource.venv/bin/activate uv pipinstalltorch==2.6.0torchvision==0.21.0torchaudio==2.6.0\--index-url https://download.pytorch.org/whl/cu126

方案 B：全新安装时使用 PyTorch 当前版本

PyTorch 的可用版本和 CUDA wheel 会变化。打开 PyTorch 官方安装选择器，选择：

OS：Linux Package：Pip Language：Python Compute Platform：适合当前驱动的 CUDA 版本

复制官网生成的安装命令，并把开头的pip install改成uv pip install。例如，官网若给出：

pipinstalltorch torchvision torchaudio --index-url<官网给出的地址>

则在已激活的虚拟环境中执行：

uv pipinstalltorch torchvision torchaudio --index-url<官网给出的地址>

不要只根据nvidia-smi显示的 CUDA 数字随意拼接下载地址；应使用 PyTorch 官网当前提供的 wheel。

验证 PyTorch 和 GPU

先做最简单的检查：

python-c"import torch; print(torch.cuda.is_available())"

应输出：

True

再查看完整信息：

python -<<'PY' import torch print("PyTorch:", torch.__version__) print("PyTorch CUDA runtime:", torch.version.cuda) print("CUDA 可用:", torch.cuda.is_available()) if torch.cuda.is_available(): print("GPU:", torch.cuda.get_device_name(0)) print("显存:", round(torch.cuda.get_device_properties(0).total_memory / 1024**3, 2), "GB") PY

如果这里是False，不要继续安装其他可选 GPU 组件，先处理“常见错误”中的 GPU/PyTorch 问题。

八、安装 LLaMA-Factory

确认虚拟环境仍处于激活状态：

cd~/LlamaFactorysource.venv/bin/activate

安装 LLaMA-Factory 源码和评估指标依赖：

uv pipinstall-e.uv pipinstall-rrequirements/metrics.txt

可选：安装 bitsandbytes

如果要使用 4-bit/8-bit 量化加载或 QLoRA，再安装bitsandbytes：

uv pipinstallbitsandbytes --no-deps

使用 uv 时，把bitsandbytes放在 GPU 版 PyTorch 之后安装，并使用--no-deps，可减少它重新解析或替换 PyTorch 的风险。

如果只做普通推理或不使用量化训练，可以先不安装。

不建议一开始就安装 FlashAttention、DeepSpeed 等可选组件。先让基础环境和 WebUI 正常运行，再按具体训练需求单独安装，排错会简单很多。

九、完整验证环境

检查依赖是否存在明显冲突：

uv pip check

检查 LLaMA-Factory：

llamafactory-cli version

检查核心组件：

python -<<'PY' import importlib.util import torch import transformers import datasets import peft import trl import llamafactory print("核心 Python 组件：正常") print("CUDA 可用：", torch.cuda.is_available()) print("GPU：", torch.cuda.get_device_name(0) if torch.cuda.is_available() else "未识别") print("bitsandbytes：", "已安装" if importlib.util.find_spec("bitsandbytes") else "未安装（可选）") PY

三项检查都通过后，再启动 WebUI。

十、规划模型、数据集和输出目录

模型缓存通常比程序本身占用更多空间。建议预先创建独立目录：

mkdir-p"$HOME/models/huggingface"mkdir-p"$HOME/llamafactory-data"mkdir-p"$HOME/llamafactory-output"

把 Hugging Face 缓存位置永久写入 Bash 配置：

grep-qxF'export HF_HOME="$HOME/models/huggingface"'"$HOME/.bashrc"||\echo'export HF_HOME="$HOME/models/huggingface"'>>"$HOME/.bashrc"source"$HOME/.bashrc"

检查：

echo"$HF_HOME"

应显示：

/home/<你的用户名>/models/huggingface

说明：

• HF_HOME控制 Hugging Face 的缓存、令牌等存储位置；模型仓库缓存默认位于$HF_HOME/hub。
• ~/llamafactory-data可用于保存自己的原始数据；使用自定义数据集时，仍需按 LLaMA-Factory 的格式配置data/dataset_info.json。
• ~/llamafactory-output可作为训练输出、checkpoint 和导出模型目录；在 WebUI 中把输出路径指向该目录。
• 缓存不是备份。重要数据集、配置和训练结果仍应另行备份。

查看空间占用：

df-hdu-sh"$HF_HOME""$HOME/llamafactory-output"2>/dev/null

十一、启动 WebUI

手动启动：

cd~/LlamaFactorysource.venv/bin/activate llamafactory-cli webui

看到终端输出访问地址后，在 Windows 浏览器打开：

http://localhost:7860

保持 Ubuntu 终端窗口运行。关闭服务时，在该终端按：

Ctrl + C

然后可退出虚拟环境：

deactivate

WebUI 默认仅供本机使用。不要在没有访问控制的情况下把它绑定到公网地址或开放路由器端口。

十二、设置更稳健的一键启动脚本

以下命令只需在WSL 的 Ubuntu 终端中执行一次：

cat>"$HOME/start_llamafactory.sh"<<'EOF' #!/usr/bin/env bash set -Eeuo pipefail project_dir="${LLAMAFACTORY_HOME:-$HOME/LlamaFactory}" venv_dir="$project_dir/.venv" cli="$venv_dir/bin/llamafactory-cli" if [[ ! -d "$project_dir" ]]; then echo "错误：找不到 LLaMA-Factory 目录：$project_dir" >&2 echo "请先完成安装，或设置 LLAMAFACTORY_HOME 指向正确目录。" >&2 exit 1 fi if [[ ! -x "$cli" ]]; then echo "错误：找不到可执行文件：$cli" >&2 echo "请检查项目虚拟环境，必要时重新执行 uv pip install -e ." >&2 exit 1 fi cd "$project_dir" if command -v nvidia-smi >/dev/null 2>&1; then echo "检测到 GPU：" nvidia-smi --query-gpu=name,memory.total,driver_version --format=csv,noheader || true else echo "警告：当前 WSL 中找不到 nvidia-smi，GPU 训练可能不可用。" >&2 fi export HF_HOME="${HF_HOME:-$HOME/models/huggingface}" mkdir -p "$HF_HOME" echo "Hugging Face 缓存：$HF_HOME" echo "正在启动 LLaMA-Factory WebUI……" exec "$cli" webui "$@" EOFchmod+x"$HOME/start_llamafactory.sh"

这个脚本会：

• 检查项目目录和虚拟环境是否存在；
• 显示 GPU 信息，便于第一时间发现驱动问题；
• 使用指定的 Hugging Face 缓存目录；
• 直接调用项目虚拟环境中的命令，不依赖当前终端是否已经激活环境；
• 使用exec正确传递Ctrl + C等终止信号。

以后每次打开 Ubuntu，只需执行：

~/start_llamafactory.sh

如需更短的命令，可设置别名：

grep-qF"alias lf=""$HOME/.bashrc"||\echo"alias lf='$HOME/start_llamafactory.sh'">>"$HOME/.bashrc"source"$HOME/.bashrc"

以后输入：

lf

即可启动。

十三、日常更新

如果当前环境运行稳定，不必为了“追新”频繁更新。需要更新时：

cd~/LlamaFactorygitstatusgitpull --ff-onlysource.venv/bin/activate uv pipinstall-e.uv pipinstall-rrequirements/metrics.txt uv pip check llamafactory-cli version

更新前建议备份自己的数据集配置、训练 YAML 和输出结果。如果git status显示修改过官方仓库文件，请先确认这些改动是否需要保留；不要直接覆盖。

PyTorch、CUDA wheel、bitsandbytes 或 LLaMA-Factory 跨大版本升级后，应重新运行第九节的完整验证。

十四、常见错误处理

1.uv: command not found

先执行：

source"$HOME/.local/bin/env"2>/dev/null||exportPATH="$HOME/.local/bin:$PATH"uv--version

仍无效时，关闭 Ubuntu 终端并重新打开。也可检查文件是否存在：

ls-l"$HOME/.local/bin/uv"

2. 虚拟环境建错到~/.venv

先确认当前 Python：

whichpython

如果显示/home/<用户名>/.venv/bin/python，说明环境建在主目录。先退出：

deactivate

删除前务必确认目标确实是主目录下误建的环境：

ls-ld"$HOME/.venv"

确认无误后删除它：

rm-rf--"$HOME/.venv"

然后在正确目录重建：

cd~/LlamaFactory uv venv--python3.11source.venv/bin/activate

不要删除正确的项目环境：

~/LlamaFactory/.venv

如果每次打开 Ubuntu 都自动进入错误环境，检查启动配置：

grep-nE'\.venv|activate'"$HOME/.bashrc""$HOME/.profile"2>/dev/null

找到类似source ~/.venv/bin/activate的误配置后，用编辑器删除对应行，再重新打开终端。

3. WSL 中执行nvidia-smi失败

按顺序检查：

1. 在 Windows PowerShell 中执行nvidia-smi，确认 Windows 驱动正常。
2. 更新 Windows NVIDIA 驱动。
3. 在 Windows PowerShell 中执行wsl --update。
4. 保存 WSL 中的工作后，在 Windows PowerShell 中执行wsl --shutdown，再重新打开 Ubuntu。
5. 确认wsl -l -v中 Ubuntu 使用的是 WSL2。

不要通过安装 Ubuntu 的nvidia-driver-*包来“修复”此问题。

4.torch.cuda.is_available()返回False

先确认nvidia-smi在 WSL 中正常。如果正常，很可能安装了 CPU 版或不合适的 PyTorch wheel。

在项目虚拟环境中删除现有 PyTorch：

cd~/LlamaFactorysource.venv/bin/activate uv pip uninstall torch torchvision torchaudio

再按第七节，从 PyTorch 官方安装选择器复制正确的 Linux + Pip + CUDA 命令，并用uv pip install安装。完成后重新检查：

python-c"import torch; print(torch.__version__); print(torch.version.cuda); print(torch.cuda.is_available())"

5.llamafactory-cli: command not found

确认当前目录和 Python 环境：

cd~/LlamaFactorysource.venv/bin/activatewhichpython

重新安装项目：

uv pipinstall-e.llamafactory-cli version

6.No space left on device

检查磁盘和大目录：

df-hdu-sh"$HOME/models""$HOME/llamafactory-output""$HOME/.cache"2>/dev/null

优先清理确认不再需要的 checkpoint、导出模型和旧缓存。不要在不了解文件用途时直接删除整个模型或输出目录。

7. 端口 7860 已被占用

先确认是否已经在另一个终端启动过 WebUI：

ss-ltnp|grep':7860'

如果是之前启动的 LLaMA-Factory，请回到原终端按Ctrl + C停止，再重新启动。不要同时启动多个实例，尤其是在 8 GB 显存设备上。

8. 出现 localhost 代理提示

例如：

wsl: 检测到 localhost 代理配置，但未镜像到 WSL。 NAT 模式下的 WSL 不支持 localhost 代理。

这条提示本身不代表安装失败。如果git clone和依赖下载都正常，可以忽略。若下载失败，则需要让 WSL 使用可访问的代理地址，或在受支持的 Windows/WSL 版本中配置镜像网络；不要把代理问题误判为 LLaMA-Factory 安装错误。

9. 训练时显存不足（CUDA out of memory）

8 GB 显存建议先从 1.5B～4B 模型和 4-bit QLoRA 开始。7B 4-bit QLoRA 可以尝试，但官方估算的最低显存不包含所有实际开销，序列长度、批次、优化器状态和缓存都可能导致显存不足。

优先尝试：

• 减小cutoff_len；
• 把每设备批次设为 1；
• 使用梯度累积保持有效批次；
• 开启梯度检查点；
• 使用 4-bit 量化；
• 关闭同时占用 GPU 的其他程序；
• 先用更小模型验证完整训练流程。

十五、快速检查清单

安装完成后，应满足：

• wsl -l -v显示 Ubuntu 使用 WSL2；
• WSL 中的nvidia-smi能看到 NVIDIA GPU；
• 没有在 WSL 中安装 Linux NVIDIA 显示驱动；
• 项目位于~/LlamaFactory，而不是/mnt/c/...；
• uv --version正常；
• which python指向~/LlamaFactory/.venv/bin/python；
• torch.cuda.is_available()返回True；
• uv pip check没有依赖冲突；
• llamafactory-cli version正常；
• http://localhost:7860能打开 WebUI；
• 已规划 Hugging Face 缓存和训练输出目录；
• 一键启动脚本可正常启动，并能用Ctrl + C停止。

官方参考

• Microsoft：安装 WSL
• Microsoft：WSL 基本命令
• NVIDIA：CUDA on WSL User Guide
• LLaMA-Factory 官方仓库与安装说明
• PyTorch：Get Started
• uv：安装说明
• uv：虚拟环境
• Hugging Face：环境变量与 HF_HOME