八个必需依赖与五个可选依赖：版本下限和推荐值分别卡在哪
本文所有事实以
hiyouga/LlamaFactory官方仓库 2026-08-09 的内容为准。我们没有安装、训练或部署过任何模型，文中版本号均照抄仓库文档原文。
装这类训练框架最常见的翻车顺序是这样的：先照着 pip install -e . 敲完，跑起来报一个看不懂的错，回头搜半天，最后发现是 transformers 版本比人家要求的低了两个小版本。而这件事其实在 README 的 Installation 一节里就写着——那里有两张 Requirement 表，一张 Mandatory 八行，一张 Optional 五行，每行都分了 Minimum 和 Recommend 两列。
这篇只干一件事：把这十三行摊开讲清楚。哪一行是真的硬下限，哪几行只有在你用到某个具体功能时才需要，这些数字分别写在哪一层，以及为什么读完这两张表你还是拿不到一份”这几个版本一起用就对了”的组合清单。
先分清 Minimum 和 Recommend 是两条线
这两列不是”低配”和”高配”的意思。按 README 的表头字面理解：Minimum 是这个依赖被接受的最低版本，Recommend 是官方给出的推荐取值。两列都是官方文档口径，我们没有装过任何一个组合去验证它们，所以下面全程只做转述和对照，不做”哪个组合能跑”的判断。
有一个细节值得先点出来：八条 Mandatory 里，只有 python 这一行的 Recommend 写成了 >=3.11 这种区间形式，其余七行的 Recommend 都是一个具体版本号。也就是说 Python 这一项官方给的是”3.11 起步、往上不设限”，而其它依赖给的是一个点值。这是从表里直接读出来的写法差异，至于为什么这么写，README 没说，我们也不推断。
八条 Mandatory：逐格照抄
| 依赖 | Minimum | Recommend |
|---|---|---|
| python | 3.11 | >=3.11 |
| torch | 2.0.0 | 2.6.0 |
| torchvision | 0.15.0 | 0.21.0 |
| transformers | 4.49.0 | 4.50.0 |
| datasets | 2.16.0 | 3.2.0 |
| accelerate | 0.34.0 | 1.2.1 |
| peft | 0.14.0 | 0.15.1 |
| trl | 0.8.6 | 0.9.6 |
读这张表的时候，按”这一行卡住的是哪一环”分一下组，比从上往下扫一遍有用：
python 是最先该确认的一行。 Minimum 3.11、Recommend >=3.11，两列都从 3.11 起。这意味着如果你手上是更老的解释器环境，其它七行你连看都不用看，先解决 Python 版本再谈别的。这一行的下限和推荐值撞在同一个数上，是八行里唯一一处，值得单独记住。
torch 与 torchvision 是成对的一组。 torch 的跨度是 Minimum 2.0.0 到 Recommend 2.6.0，torchvision 是 0.15.0 到 0.21.0。这两行的 Minimum 与 Recommend 之间隔了不小的一段——你可以把这理解成官方在两端各画了一条线，中间那一大片没有表态。至于这两个版本号之间该取哪一个，README 没说，我们也没有装过任何一个组合来验证。
剩下五行是 Hugging Face 那一套生态。 transformers 4.49.0 / 4.50.0，datasets 2.16.0 / 3.2.0，accelerate 0.34.0 / 1.2.1，peft 0.14.0 / 0.15.1，trl 0.8.6 / 0.9.6。这五个里最容易被忽略的是 peft 和 trl：它们各自具体承担什么，README 的 Requirement 表里没有展开写，我们也不替它补——这里只按表面事实说一句，它们被放在 Mandatory 表里而不是 Optional 表里，也就是说不管你这次只想跑一个最简单的监督微调，按这张表它们也一样在必装之列。
值得注意的是版本跨度：datasets 的 Minimum 是 2.x（2.16.0）而 Recommend 已经是 3.x（3.2.0），accelerate 是 0.34.0 到 1.2.1，同样跨过了一次主版本号。八行里就这两行的 Minimum 与 Recommend 分属不同主版本，其余各行的两列都在同一个主版本内。这同样是从表里数出来的，不涉及任何”该选哪个”的建议。
这张表落在哪一层，以及 Installation is mandatory.
README 在安装这一节用 > [!IMPORTANT] 单独强调了一句 Installation is mandatory.——这个项目不接受”先不装、直接跑源码试试”的路子。
从源码装的四行原文是：
git clone --depth 1 https://github.com/hiyouga/LlamaFactory.git
cd LlamaFactory
pip install -e .
pip install -r requirements/metrics.txt
这四行和上面那张表的关系是：pip install -e . 负责的是包本身及其声明的依赖，而 Requirement 表是 README 用人话把版本区间列给你看的一层说明。两张 Requirement 表之外，仓库里还有两处地方也在管依赖：一是 requirements/ 目录下的 metrics.txt、deepspeed.txt 这类可选依赖清单，README 给了一次装两个的写法：
pip install -e . && pip install -r requirements/metrics.txt -r requirements/deepspeed.txt
二是 examples/requirements/，README 说特定功能的额外依赖放在那里。所以”依赖”这件事在这个仓库里至少分布在三处：README 的两张表、requirements/ 下的可选清单、examples/requirements/ 下的功能级清单。查版本问题时，只翻 README 那张表是不够的。
五条 Optional：每一条都绑着一类具体功能
| 依赖 | Minimum | Recommend |
|---|---|---|
| CUDA | 11.6 | 12.2 |
| deepspeed | 0.10.0 | 0.16.4 |
| bitsandbytes | 0.39.0 | 0.43.1 |
| vllm | 0.4.3 | 0.8.2 |
| flash-attn | 2.5.6 | 2.7.2 |
Optional 这个词容易被误读成”锦上添花”。更准确的读法是：它们不是全局必需，但只要你要用对应的那类功能，对应的那一行就变成必需的了。 按 README 里 Features 那八条的措辞，能对上的挂钩关系是这样的：
bitsandbytes对应的是 Scalable resources 那一条里的 QLoRA。README 在那条里写的是通过 AQLM / AWQ / GPTQ / LLM.int8 / HQQ / EETQ 实现 2/3/4/5/6/8-bit QLoRA。也就是说，你只要打算走量化微调这条线，这一行就得看。vllm对应的是 Faster inference 那一条：README 写明推理侧可以接 vLLM worker 或 SGLang worker。如果你只训练、训完把权重导出去交给别的服务，这一行可以先放着。flash-attn对应的是 Practical tricks 那一条里的 FlashAttention-2。同一条里还列了 Unsloth、Liger Kernel、KTransformers、RoPE scaling、NEFTune、rsLoRA——README 的这一条只说明这些技巧被集成进来了，至于它们各自是否默认启用、怎么开，Features 那八条里没写，本文也不猜。deepspeed在仓库里有一份专门的requirements/deepspeed.txt，也是 README 明确点名的两个可选依赖之一（另一个是metrics）。CUDA这一行和上面四行的性质不太一样，它不是一个 pip 包，而是你机器上的那一层。README 另有一张 Hardware Requirement 表列了各方法在不同参数规模下的显存量级，但那张表在表头上方被 README 自己标了* estimated（估算），不是实测占用，我们也没有跑过任何一次训练，所以这里不据此给”你的卡够不够”的结论。那张表我们另有一篇专门讲。
至于 Ascend NPU 这条线，README 的折叠块里给了一个和量化直接相关的具体提示：在配置里设 double_quantization: false，并给了参考示例 examples/train_qlora/qwen3_lora_sft_bnb_npu.yaml。这一条只在 NPU 场景下出现，用不上就跳过。
官方 Docker 镜像给出了一组具体版本，可以拿来对照
如果你想避开自己拼版本这件事，README 给的 Docker 路径是：
docker run -it --rm --gpus=all --ipc=host hiyouga/llamafactory:latest
README 原文写明这个镜像基于 Ubuntu 22.04 (x86_64)、CUDA 12.4、Python 3.11、PyTorch 2.6.0、Flash-attn 2.7.4。预构建镜像列表在 Docker Hub 的 tags 页；要自建的话，README 给的是 cd docker/docker-cuda/ 然后 docker compose up -d，仓库 docker/ 目录下按后端分了子目录。
把这组数字和上面两张表并排看，能读出几处对照：
- Python 3.11、PyTorch 2.6.0 分别对应 Mandatory 表里 python 的下限和 torch 的
Recommend； - 镜像里的 CUDA 是 12.4，而 Optional 表里 CUDA 的
Recommend是 12.2； - 镜像里的 Flash-attn 是 2.7.4，而 Optional 表里 flash-attn 的
Recommend是 2.7.2。
后两处是同一个依赖在仓库的两个位置上出现了不同的版本号：一处是 Optional 表里的 Recommend，一处是 README 写明的镜像内置版本。我们只如实指出这个差异，不推断哪个才是”该用的那个”，也不推断为什么两处不一样。对你的实际影响只有一条：如果你要照着镜像的版本组合去本地复刻，别把 README 表里的 Recommend 当成镜像里的实际版本。
另外，README 的折叠块里还给了 uv 的用法示例，用来建隔离环境：
uv run llamafactory-cli webui
Windows 侧单独记的两行
依赖装完之后，很多人卡住的下一步是模型下不动。README 给的处置是切下载源，环境变量的写法在两个平台上不一样，这里分开写：
切到 ModelScope Hub：
# Linux / macOS
export USE_MODELSCOPE_HUB=1
:: Windows
set USE_MODELSCOPE_HUB=1
然后把 model_name_or_path 填成 ModelScope 的 model ID，README 给的例子是 LLM-Research/Meta-Llama-3-8B-Instruct。
切到 Modelers Hub 是同一套写法，变量换成 USE_OPENMIND_HUB=1，model ID 示例是 TeleAI/TeleChat-7B-pt。同样地，Linux/macOS 用 export，Windows 用 set。
那么，该把版本锁在哪
这个问题官方没给答案，我们也不替它给。
两张 Requirement 表提供的是每个依赖各自的一条下限和一个推荐点，没有任何一处给出”这几个版本一起用”的组合矩阵。唯一一组被官方同时写出来的具体版本，就是 Docker 镜像那五个数字，而其中两个还高于表里对应的 Recommend。具体锁哪个版本取决于你的显卡、驱动、要不要用量化、要不要接推理 worker——这些条件官方没给通用值，我们也没有装过任何一个组合来验证。
真正能拿走的操作顺序倒是清楚的：
- 先确认 Python，两列都是 3.11 起，这一行不满足，后面都白搭；
- 再确认 torch / torchvision 这一对，以及机器上的 CUDA 层；
- 然后按你要用的功能勾 Optional：走量化看
bitsandbytes，要接推理服务看vllm，要开 FlashAttention-2 看flash-attn，要上deepspeed就顺手把requirements/deepspeed.txt一起装了； - 不想拼版本就直接用官方镜像，代价是接受它固定的那组 Ubuntu / CUDA / Python / PyTorch / Flash-attn 组合。
最后提醒一句仓库里的名字问题：hiyouga/LlamaFactory 是当前的真实路径，但仓库内部新旧写法并存，src/llamafactory/launcher.py 的欢迎语里写的项目主页仍是带连字符的旧名 https://github.com/hiyouga/LLaMA-Factory，README 正文里两种拼法也都出现过。搜依赖报错、翻 issue 的时候两种拼法都试一遍，别因为拼写不同就以为搜到的是另一个项目。
本文依据 LlamaFactory 官方仓库（github.com/hiyouga/LlamaFactory）的 README、data/README.md、examples/ 下的配置与 src/llamafactory/hparams/ 的参数定义整理，核对日 2026-08-09。本文内容为仓库源码与文档口径，我们没有安装、训练或部署过任何模型，文中显存数字均为官方标注的估算值（README 原文标 * estimated）而非实测占用。参数与默认值随版本变动，请以 llamafactory-cli train -h 的实际输出为准。