在 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 文件系统。本文曾验证过的机器配置为GPUNVIDIA GeForce RTX 4060 Laptop GPU8 GB Python3.11 PyTorch2.6.0 CUDA 12.6 wheel软件版本会更新。全新安装时应同时参考LLaMA-Factory 官方仓库PyTorch 官方安装选择器uv 官方安装说明NVIDIA CUDA on WSL 指南一、安装并检查 WSL21. 首次安装 WSL仅首次安装时用管理员身份打开 Windows PowerShellwsl--install-d Ubuntu如果系统提示重启请先重启 Windows。第一次打开 Ubuntu 时按提示创建 Linux 用户名和密码。更新 WSLwsl--update检查 Ubuntu 是否运行在 WSL2wsl-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 GPU1. 在 Windows 中安装显卡驱动从 NVIDIA 官方渠道安装或更新 Windows 显卡驱动。安装完成后可在 Windows PowerShell 中检查nvidia-smi2. 在 WSL 中检查显卡打开 Ubuntu执行nvidia-smi再查看简要信息nvidia-smi --query-gpuname,memory.total,driver_version--formatcsv,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让当前终端立即识别uvsource$HOME/.local/bin/env2/dev/null||exportPATH$HOME/.local/bin:$PATH检查安装结果uv--version如果仍提示uv: command not found关闭 Ubuntu 终端并重新打开再执行uv --version。以后更新 uvuv 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/activateuv会在需要时自动下载合适的 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 pipinstalltorch2.6.0torchvision0.21.0torchaudio2.6.0\--index-url https://download.pytorch.org/whl/cu126方案 B全新安装时使用 PyTorch 当前版本PyTorch 的可用版本和 CUDA wheel 会变化。打开 PyTorch 官方安装选择器选择OSLinux PackagePip LanguagePython 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-cimport 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再安装bitsandbytesuv pipinstallbitsandbytes --no-deps使用 uv 时把bitsandbytes放在 GPU 版 PyTorch 之后安装并使用--no-deps可减少它重新解析或替换 PyTorch 的风险。如果只做普通推理或不使用量化训练可以先不安装。不建议一开始就安装 FlashAttention、DeepSpeed 等可选组件。先让基础环境和 WebUI 正常运行再按具体训练需求单独安装排错会简单很多。九、完整验证环境检查依赖是否存在明显冲突uv pip check检查 LLaMA-Factoryllamafactory-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/huggingfacemkdir-p$HOME/llamafactory-datamkdir-p$HOME/llamafactory-output把 Hugging Face 缓存位置永久写入 Bash 配置grep-qxFexport HF_HOME$HOME/models/huggingface$HOME/.bashrc||\echoexport HF_HOME$HOME/models/huggingface$HOME/.bashrcsource$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-output2/dev/null十一、启动 WebUI手动启动cd~/LlamaFactorysource.venv/bin/activate llamafactory-cli webui看到终端输出访问地址后在 Windows 浏览器打开http://localhost:7860保持 Ubuntu 终端窗口运行。关闭服务时在该终端按Ctrl C然后可退出虚拟环境deactivateWebUI 默认仅供本机使用。不要在没有访问控制的情况下把它绑定到公网地址或开放路由器端口。十二、设置更稳健的一键启动脚本以下命令只需在WSL 的 Ubuntu 终端中执行一次cat$HOME/start_llamafactory.shEOF #!/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 21; then echo 检测到 GPU nvidia-smi --query-gpuname,memory.total,driver_version --formatcsv,noheader || true else echo 警告当前 WSL 中找不到 nvidia-smiGPU 训练可能不可用。 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 $ EOFchmodx$HOME/start_llamafactory.sh这个脚本会检查项目目录和虚拟环境是否存在显示 GPU 信息便于第一时间发现驱动问题使用指定的 Hugging Face 缓存目录直接调用项目虚拟环境中的命令不依赖当前终端是否已经激活环境使用exec正确传递Ctrl C等终止信号。以后每次打开 Ubuntu只需执行~/start_llamafactory.sh如需更短的命令可设置别名grep-qFalias lf$HOME/.bashrc||\echoalias lf$HOME/start_llamafactory.sh$HOME/.bashrcsource$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/env2/dev/null||exportPATH$HOME/.local/bin:$PATHuv--version仍无效时关闭 Ubuntu 终端并重新打开。也可检查文件是否存在ls-l$HOME/.local/bin/uv2. 虚拟环境建错到~/.venv先确认当前 Pythonwhichpython如果显示/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/.profile2/dev/null找到类似source ~/.venv/bin/activate的误配置后用编辑器删除对应行再重新打开终端。3. WSL 中执行nvidia-smi失败按顺序检查在 Windows PowerShell 中执行nvidia-smi确认 Windows 驱动正常。更新 Windows NVIDIA 驱动。在 Windows PowerShell 中执行wsl --update。保存 WSL 中的工作后在 Windows PowerShell 中执行wsl --shutdown再重新打开 Ubuntu。确认wsl -l -v中 Ubuntu 使用的是 WSL2。不要通过安装 Ubuntu 的nvidia-driver-*包来“修复”此问题。4.torch.cuda.is_available()返回False先确认nvidia-smi在 WSL 中正常。如果正常很可能安装了 CPU 版或不合适的 PyTorch wheel。在项目虚拟环境中删除现有 PyTorchcd~/LlamaFactorysource.venv/bin/activate uv pip uninstall torch torchvision torchaudio再按第七节从 PyTorch 官方安装选择器复制正确的 Linux Pip CUDA 命令并用uv pip install安装。完成后重新检查python-cimport 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 version6.No space left on device检查磁盘和大目录df-hdu-sh$HOME/models$HOME/llamafactory-output$HOME/.cache2/dev/null优先清理确认不再需要的 checkpoint、导出模型和旧缓存。不要在不了解文件用途时直接删除整个模型或输出目录。7. 端口 7860 已被占用先确认是否已经在另一个终端启动过 WebUIss-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 memory8 GB 显存建议先从 1.5B4B 模型和 4-bit QLoRA 开始。7B 4-bit QLoRA 可以尝试但官方估算的最低显存不包含所有实际开销序列长度、批次、优化器状态和缓存都可能导致显存不足。优先尝试减小cutoff_len把每设备批次设为 1使用梯度累积保持有效批次开启梯度检查点使用 4-bit 量化关闭同时占用 GPU 的其他程序先用更小模型验证完整训练流程。十五、快速检查清单安装完成后应满足wsl -l -v显示 Ubuntu 使用 WSL2WSL 中的nvidia-smi能看到 NVIDIA GPU没有在 WSL 中安装 Linux NVIDIA 显示驱动项目位于~/LlamaFactory而不是/mnt/c/...uv --version正常which python指向~/LlamaFactory/.venv/bin/pythontorch.cuda.is_available()返回Trueuv pip check没有依赖冲突llamafactory-cli version正常http://localhost:7860能打开 WebUI已规划 Hugging Face 缓存和训练输出目录一键启动脚本可正常启动并能用Ctrl C停止。官方参考Microsoft安装 WSLMicrosoftWSL 基本命令NVIDIACUDA on WSL User GuideLLaMA-Factory 官方仓库与安装说明PyTorchGet Starteduv安装说明uv虚拟环境Hugging Face环境变量与 HF_HOME