{"id":9895,"library":"lightning-fabric","title":"Lightning Fabric","description":"Lightning Fabric is a lightweight, high-performance library for training deep learning models at scale with PyTorch. It provides core utilities for distributed training, mixed-precision, and device management, allowing users to write pure PyTorch code while Fabric handles the boilerplate. It is currently at version 2.6.1 and follows the release cadence of the broader Lightning ecosystem, typically with monthly or bi-monthly patch releases.","status":"active","version":"2.6.1","language":"en","source_language":"en","source_url":"https://github.com/Lightning-AI/lightning","tags":["deep learning","pytorch","distributed training","GPU","multi-GPU","mixed precision","data parallel"],"install":[{"cmd":"pip install lightning-fabric torch","lang":"bash","label":"Install Fabric and PyTorch"}],"dependencies":[{"reason":"Deep learning backend","package":"torch","optional":false}],"imports":[{"note":"Fabric was introduced as part of the unified Lightning ecosystem (Lightning 2.0+). Older imports from `pytorch_lightning` might not contain `Fabric` or refer to deprecated structures.","wrong":"from pytorch_lightning.fabric import Fabric","symbol":"Fabric","correct":"from lightning.fabric import Fabric"}],"quickstart":{"code":"import os\nimport torch\nfrom torch.utils.data import DataLoader, TensorDataset\nfrom lightning.fabric import Fabric\n\n# 1. Initialize Fabric\n# Configure accelerators, devices, precision. E.g., Fabric(accelerator='cpu', precision='bf16')\n# For a basic setup, Fabric() will try to use available GPUs or CPU.\nfabric = Fabric(\n    accelerator=os.environ.get('ACCELERATOR', 'auto'),\n    devices=os.environ.get('DEVICES', 'auto'),\n    precision=os.environ.get('PRECISION', '32-true')\n)\n\n# 2. Define your model, optimizer, and data\nmodel = torch.nn.Linear(10, 2)\noptimizer = torch.optim.SGD(model.parameters(), lr=0.01)\n\n# Generate dummy data\nX = torch.randn(100, 10)\ny = torch.randint(0, 2, (100,))\ndataset = TensorDataset(X, y)\ndataloader = DataLoader(dataset, batch_size=16)\n\n# 3. Setup the model, optimizer, and data for distributed training\nmodel, optimizer = fabric.setup(model, optimizer)\ndataloader = fabric.setup_dataloader(dataloader)\n\n# 4. Training loop\nfabric.print(f\"Starting training on device: {fabric.device}\")\nfor epoch in range(3):\n    for batch_idx, (data, target) in enumerate(dataloader):\n        optimizer.zero_grad()\n        output = model(data)\n        loss = torch.nn.functional.cross_entropy(output, target)\n        fabric.backward(loss) # Perform backward pass using Fabric\n        optimizer.step()\n\n        if batch_idx % 10 == 0:\n            fabric.print(f\"Epoch {epoch}, Batch {batch_idx}, Loss: {loss.item():.4f}\")\n\nfabric.print(\"Training complete!\")\n\n# Example of saving: fabric.save(\"model.pt\", {\"model\": model.state_dict(), \"optimizer\": optimizer.state_dict()})\n","lang":"python","description":"This quickstart demonstrates how to use Lightning Fabric to set up a simple PyTorch model for training, leveraging Fabric for device management, mixed precision, and distributed training boilerplate. It covers initialization, model/optimizer/dataloader setup, and a basic training loop with a backward pass handled by Fabric."},"warnings":[{"fix":"Refer to the official Lightning Fabric 2.x documentation for updated API usage, especially for `Fabric` initialization, `setup`, and manual training loop construction.","message":"Users migrating from PyTorch Lightning 1.x to the Lightning 2.x ecosystem (which includes Fabric) will encounter significant API changes. Fabric adopts a more explicit, less opinionated approach to distributed training and device placement compared to the `Trainer` in PL 1.x.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Embrace the 'pure PyTorch' philosophy; use Fabric's `setup` methods and `backward` for core distributed operations, but manage the loop structure, metrics, and logging yourself.","message":"Lightning Fabric provides low-level distributed training primitives. It does not include a full `Trainer` abstraction like `pytorch_lightning.Trainer`. Users are responsible for writing their own training loops, validation loops, and handling callbacks manually.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always use `fabric.setup()` for your model and optimizer, and `fabric.setup_dataloader()` for your data loaders. Fabric will handle the device placement. Avoid manual `to(device)` calls on objects managed by Fabric.","message":"Incorrect device placement (e.g., calling `.cuda()` or `.to(device)` directly on tensors or modules after Fabric has already set them up) can lead to unexpected behavior or errors, especially in distributed environments.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Ensure all models, optimizers, and data loaders are passed through `fabric.setup()` and `fabric.setup_dataloader()` respectively. Verify that any custom tensor creation inside your model or dataloader explicitly uses `fabric.device` or is handled by Fabric's setup.","cause":"This typically occurs when tensors are inadvertently created or moved to different devices (e.g., CPU vs. GPU, or different GPUs) without Fabric's orchestration, often in data loading or custom modules.","error":"RuntimeError: Expected all tensors to be on the same device, but found at least two devices"},{"fix":"Fabric requires you to write the training loop explicitly. It provides tools like `fabric.setup()` and `fabric.backward()` to help, but the loop control is manual.","cause":"Users often confuse Lightning Fabric with PyTorch Lightning's Trainer. Fabric does not provide a high-level `fit` method.","error":"AttributeError: 'Fabric' object has no attribute 'fit'"},{"fix":"Update your import statement to `from lightning.fabric import Fabric`.","cause":"The `Fabric` class was moved to the top-level `lightning.fabric` package as part of the Lightning 2.0 refactor. The old import path is no longer valid.","error":"ImportError: cannot import name 'Fabric' from 'pytorch_lightning.fabric'"},{"fix":"Ensure `torch` is installed with CUDA support if you intend to use GPUs. Explicitly set the `accelerator` and `devices` parameters during `Fabric` initialization (e.g., `Fabric(accelerator='cuda', devices=1)` or `Fabric(accelerator='cpu')`).","cause":"This can happen if Fabric cannot infer the appropriate device (e.g., GPU) or if you're trying to use a specific accelerator without it being properly installed or configured (e.g., trying to use CUDA without PyTorch installed with CUDA support).","error":"TypeError: Expected one of device type attribute to be present, but found none."}]}