PyTorch Lightning 安装完全指南:pip、Conda、源码构建与依赖矩阵详解

原创2026-09-19 14:57:221,859 阅读
文章标签:人工智能深度学习机器学习预训练分布式训练

PyTorch Lightning 安装完全指南:pip、Conda、源码构建与依赖矩阵详解

本篇指南系统讲解 PyTorch Lightning(当前仓库 README.md 所述 "The deep learning framework to pretrain and finetune AI models")的安装路径:从最常用的 pip 与 conda 安装,到源码构建 nightly / stable 分支、自定义 PyTorch 版本,再到面向生产部署的 lightning<a href="https://link.gitcode.com/i/f3f319e813aee5f71007cc24b719cc8e" target="_blank">apps] 优化包。读完你将掌握不同场景下应选择的安装命令、仓库中 extras 可选依赖的真实构成,以及如何依据 [版本兼容矩阵 匹配 Python、PyTorch 与 torchmetrics 的版本。

安装前须知

PyTorch Lightning 的官方安装文档(docs/source-pytorch/starter/installation.rst)明确建议:务必在虚拟环境(virtual env)或 conda 环境中安装,避免污染系统级 Python,也便于不同项目锁定不同依赖版本。

从仓库结构看,当前项目采用单一仓库多包结构:lightning 是一个聚合包,其下包含 lightning.pytorch(PyTorch Lightning 训练框架)与 lightning.fabric(低层分布式原语库),源码位于 src/lightning/。安装 lightning 一个包即可获得全部能力,这也是官方推荐的方式。

使用 pip 安装

在虚拟环境或 conda 环境中,直接通过 pip 安装:

python -m pip install lightning

该命令会从 PyPI 拉取 lightning 主包及其运行依赖。根据 src/lightning/setup.py 中的 install_requires 定义,lightning 的安装依赖除了从 requirements/pytorch/base.txt 聚合的基础依赖(如 torch、tqdm、PyYAML、fsspec、torchmetrics、packaging、typing-extensions、lightning-utilities 等)之外,还会显式依赖 pytorch-lightning 包以保持兼容性。

值得注意的是,requirements/pytorch/base.txt 中标注的版本上界(如 torch >=2.6.0, <2.14.0)主要用于 CI 稳定性控制,在正式安装包时这些上界会被放宽(文件中注释原文:"the upper bound for the package version is only set for CI stability, and it is dropped while installing this package")。若你需要严格约束某个依赖的版本范围,可在该文件对应行添加 strict 行内注释来保留限制。

安装可选依赖(extras)

如果你需要完整功能(日志、调参、策略扩展等),可以使用 extras 语法。从 src/lightning/setup.py 的 _prepare_extras() 实现可知,仓库会扫描 requirements/ 下各子目录的 *.txt 文件并自动生成 extras 组,包括:

pip install "lightning[pytorch-extra]"      # 完整功能扩展依赖
pip install "lightning[pytorch-strategies]" # 分布式策略(如 deepspeed)
pip install "lightning[pytorch-examples]"   # 运行 examples 所需依赖
pip install "lightning[pytorch-all]"        # 上述三类合并
pip install "lightning[pytorch-dev]"        # 全部 + 测试依赖

同时,_prepare_extras() 还会把每个子包的 extras 合并为无前缀的公共组名,因此下面这些写法同样有效:

pip install "lightning[extra]"
pip install "lightning[strategies]"
pip install "lightning[examples]"
pip install "lightning[all]"
pip install "lightning[dev]"

具体内容对应关系可对照 requirements/pytorch/extra.txt(matplotlib、omegaconf、hydra-core、jsonargparse、rich、tensorboardX、bitsandbytes 等)、requirements/pytorch/strategies.txt(deepspeed,排除 Windows 与 Darwin 平台)与 requirements/pytorch/examples.txt(requests、torchvision、ipython、torchmetrics 等)。fabric 侧对应 requirements/fabric/ 下的 fabric-extra、fabric-strategies、fabric-examples 等组。

使用 Conda 安装

如果没有安装 conda,请先参考 Conda 官方安装指南完成 conda 的安装;Lightning 在 conda-forge 频道发布,安装命令为:

conda install lightning -c conda-forge

更规范的做法是先创建并激活专属环境,再安装:

conda activate my_env
conda install lightning -c conda-forge

关于 Apple Silicon 上的 grpcio 问题

官方文档提示:如果你在拉取 GRPC 包时遇到困难(例如在 Apple M1 芯片的 macOS 上),可以参考社区关于如何在 Apple M1 笔记本上安装 grpcio 的讨论来解决依赖冲突。

从源码构建(Build from Source)

当需要最新功能或修复时,可以从源码安装。官方文档明确区分了两种源码安装场景:

1. 安装 nightly 版本(master 分支)

pip install https://github.com/Lightning-AI/lightning/archive/refs/heads/master.zip -U

该命令直接以 zip 形式安装仓库 master 分支的代码。注意:master 分支包含所有尚未正式发布的 bug 修复与新特性,属于 "bleeding edge"(最前沿),官方文档提醒 use it at your own discretion(请自行斟酌使用),不适合生产环境。

2. 安装未来 patch release(release/stable 分支)

pip install https://github.com/Lightning-AI/lightning/archive/refs/heads/release/stable.zip -U

release/stable 分支只包含最近一个 major 版本系列的 bug 修复(patch release),不含破坏性 API 变更,稳定性远高于 master,适合想提前获得修复的用户。

从本地克隆的源码安装

如果你已经克隆了仓库,setup.py 的文档字符串说明了本地源码安装的完整场景。它支持三种粒度:

pip install .            # 安装聚合的 lightning 包(默认)
pip install -e .         # 开发模式:不复制文件,直接链接到源码,便于就地编辑调试

若只想安装单个子包,需要先设置环境变量再执行 pip:

# 只安装 pytorch_lightning
export PACKAGE_NAME=pytorch
pip install .

# 只安装 lightning_fabric
export PACKAGE_NAME=fabric
pip install .

其中 PACKAGE_NAME 的可选值与包名的映射关系定义在 setup.py 的 _PACKAGE_MAPPING(lightning / pytorch / fabric 三选一)。此外还可以用 python setup.py sdist / python setup.py bdist_wheel 构建 sdist 或 wheel 分发包。

自定义 PyTorch 版本

lightning 默认通过 PyPI 拉取满足依赖约束的 PyTorch。如果你需要特定版本的 PyTorch(例如 CUDA 版本对应的 wheel),官方文档建议:

  1. 访问 PyTorch 官方安装页面,按其指引先安装你需要的 PyTorch 版本;
  2. 再参考 Lightning 的 兼容性矩阵(docs/source-pytorch/versioning.rst 中的 "Compatibility matrix" 小节),确认该 PyTorch 版本在 Lightning 的 CI 测试覆盖范围内。

从当前仓库的兼容性矩阵可以看出,PyTorch Lightning 遵循 NEP 29 弃用策略,自 PyTorch 2.0 起力求在每个 major 版本内无破坏性变更地官方支持最新的 5 个 PyTorch minor 版本。以当前仓库对应的 2.7 版本为例,其 CI 覆盖为 torch ≥2.6(最新测试至 2.13)、torchmetrics ≥0.7.0、Python ≥3.10(最新测试至 3.13);2.5 及更早版本则支持更宽松的 Python 范围(详见矩阵表格,表中 "≥ X.Y" 为最低支持版本,"▼ X.Y" 为 CI 最后测试版本,仅供参考而非硬性上限)。超出矩阵范围的版本组合"可能非官方地正常工作",但未经 CI 验证,升级 PyTorch 前请先对照该矩阵。

面向生产部署的优化包:lightning[apps]

如果要将基于 Lightning 构建的工作流部署到生产环境、且希望依赖更少,官方文档推荐使用优化的 lightning[apps] 包:

pip install lightning-app

该包针对 ML 工作流部署场景裁剪了依赖体积,适合仅需要把训练好的 Lightning 模型/工作流投入生产、而不需要完整开发环境的用户。

安装后的验证建议

安装完成后,可以在 Python 交互环境中快速验证安装是否成功:

import lightning as L
print(L.__version__)          # 打印 lightning 包版本
from lightning.pytorch import Trainer
from lightning.fabric import Fabric

若需要跑通完整的最小训练示例,可参考 README.md 中的 Quick start 自编码器示例(pip install torchvision 后运行 python main.py),或浏览仓库 examples/pytorch/ 与 examples/fabric/ 下的真实示例。

总结:如何选择安装方式

场景 推荐命令
常规使用(推荐) python -m pip install lightning
需要完整功能与扩展 pip install "lightning[extra]" 或 pip install "lightning[all]"
conda 用户 conda install lightning -c conda-forge
体验最新特性(不推荐生产) pip install https://github.com/Lightning-AI/lightning/archive/refs/heads/master.zip -U
提前获取 patch 修复 pip install https://github.com/Lightning-AI/lightning/archive/refs/heads/release/stable.zip -U
本地源码开发调试 克隆仓库后 pip install -e .(或 PACKAGE_NAME=pytorch pip install .)
生产部署最小化依赖 pip install lightning-app

无论选择哪种方式,都建议先在隔离的虚拟环境或 conda 环境中安装,并对照 版本兼容矩阵 确认 Python、PyTorch 与 torchmetrics 的版本组合,以获得经过 CI 验证的稳定体验。

登录后查看全文
pytorch-lightning