{"id":8280,"library":"lightly","title":"Lightly","description":"Lightly is a Python library and computer vision framework for self-supervised learning, built on top of PyTorch and PyTorch Lightning. It enables training deep learning models without manual data labels, focusing on understanding and filtering raw image data for efficient active learning and data curation pipelines. The current version is 1.5.23, and it maintains an active development and release cadence.","status":"active","version":"1.5.23","language":"en","source_language":"en","source_url":"https://github.com/lightly-ai/lightly","tags":["deep learning","self-supervised learning","computer vision","pytorch","pytorch lightning","machine learning"],"install":[{"cmd":"pip install lightly","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core deep learning framework","package":"torch","optional":false},{"reason":"Computer vision utilities and datasets","package":"torchvision","optional":false},{"reason":"Simplified PyTorch training API","package":"pytorch-lightning","optional":false},{"reason":"Configuration management","package":"hydra-core","optional":false},{"reason":"Numerical operations","package":"numpy","optional":false},{"reason":"HTTP client for API interactions","package":"requests","optional":false},{"reason":"Progress bars","package":"tqdm","optional":false}],"imports":[{"note":"Main library import","symbol":"lightly","correct":"import lightly"},{"note":"Dataset class is directly under `lightly.data`","wrong":"from lightly.data.datasets import LightlyDataset","symbol":"LightlyDataset","correct":"from lightly.data import LightlyDataset"},{"note":"Self-supervised models are typically under `lightly.models.self_supervised`","wrong":"from lightly.models import MoCo","symbol":"MoCo","correct":"from lightly.models.self_supervised import MoCo"},{"note":"Loss functions are directly under `lightly.loss`","symbol":"MoCoLoss","correct":"from lightly.loss import MoCoLoss"}],"quickstart":{"code":"import torch\nimport pytorch_lightning as pl\nfrom lightly.data import LightlyDataset, collate\nfrom lightly.loss import MoCoLoss\nfrom lightly.models.self_supervised import MoCo\nfrom lightly.transforms.byol_transform import BYOLTransform\n\n# 1. Define the input dataset\n# Using a dummy dataset path for demonstration; replace with your actual image directory\n# For real use, ensure 'path_to_your_dataset' contains images\ndataset = LightlyDataset(input_dir=\"./path_to_your_dataset\")\n\n# 2. Define the data augmentations and collate function\ntransform = BYOLTransform(input_size=32)\ncollate_fn = collate(transform)\n\n# 3. Create the PyTorch DataLoader\ndataloader = torch.utils.data.DataLoader(\n    dataset,\n    batch_size=256,\n    collate_fn=collate_fn,\n    shuffle=True,\n    drop_last=True,\n    num_workers=4,\n)\n\n# 4. Define the self-supervised model\nmodel = MoCo(memory_bank_size=4096)\n\n# 5. Define the loss function\ncriterion = MoCoLoss()\n\n# 6. Define the Lightning Module for training\nclass MoCoLightningModule(pl.LightningModule):\n    def __init__(self, model, criterion):\n        super().__init__()\n        self.model = model\n        self.criterion = criterion\n\n    def training_step(self, batch, batch_idx):\n        (x0, x1), _, _ = batch\n        y0, y1 = self.model(x0, x1)\n        loss = self.criterion(y0, y1)\n        self.log(\"train_loss_ssl\", loss)\n        return loss\n\n    def configure_optimizers(self):\n        optimizer = torch.optim.SGD(self.model.parameters(), lr=0.06)\n        return optimizer\n\n# 7. Train the model\n# Ensure you have a GPU available or set accelerator='cpu'\nlightning_model = MoCoLightningModule(model, criterion)\ntrainer = pl.Trainer(max_epochs=1, accelerator=\"auto\", devices=1)\n\nprint(\"Starting Lightly self-supervised training...\")\n# Create a dummy folder if it doesn't exist to avoid errors for the quickstart\nimport os\nif not os.path.exists(\"./path_to_your_dataset\"):\n    os.makedirs(\"./path_to_your_dataset\")\n    # Optionally, create a dummy image to make it runnable without user data\n    from PIL import Image\n    Image.new('RGB', (32, 32), color = 'red').save('./path_to_your_dataset/dummy_image.png')\n\ntrainer.fit(lightning_model, dataloader)\nprint(\"Training finished. Check the logs for 'train_loss_ssl'.\")\n","lang":"python","description":"This quickstart demonstrates how to set up and train a self-supervised MoCo model using Lightly, PyTorch, and PyTorch Lightning. It covers dataset preparation, data augmentations, model definition, loss function, and the training loop with a dummy dataset. Replace './path_to_your_dataset' with your actual image directory."},"warnings":[{"fix":"Consult the official release notes and migration guides for the specific version you are upgrading to. Pay close attention to changes in public API (renaming, removal of functions/classes, altered method signatures).","message":"Lightly adheres to Semantic Versioning. Major version bumps (e.g., from 1.x to 2.x) indicate breaking changes, which may require code modifications during upgrades. Always review the release notes before upgrading major versions.","severity":"breaking","affected_versions":"<=1.x.x"},{"fix":"Ensure your development environment uses a supported Python version (e.g., Python 3.8-3.12). Check PyTorch's official documentation for Python 3.13 support status before attempting to use Lightly with it.","message":"Python 3.13 is not yet officially supported by Lightly, as its core dependency PyTorch currently lacks compatibility with Python 3.13. Users should stick to Python versions 3.7 through 3.12.","severity":"gotcha","affected_versions":"All versions up to 1.5.23"},{"fix":"Always install Lightly in a clean virtual environment and let `pip` handle the dependency resolution. If issues arise, explicitly check and upgrade `torch`, `torchvision`, and `pytorch-lightning` to the versions specified in Lightly's `setup.py` or documentation (e.g., `pytorch>=1.11.0`, `torchvision>=0.12.0`, `pytorch-lightning>=1.7.1`).","message":"Lightly has specific minimum version requirements for its core dependencies (PyTorch, Torchvision, PyTorch Lightning) to ensure all features work correctly. Older versions of these dependencies might lead to unexpected behavior or feature unavailability.","severity":"gotcha","affected_versions":"<1.5.23"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Check the official documentation for the correct import path for the specific model. For self-supervised models, they are typically in `lightly.models.self_supervised`. For standard backbones, use `torchvision.models` and pass them to Lightly's model wrappers.","cause":"Attempting to import a model from an incorrect or deprecated path. Lightly's models are often organized into submodules like `self_supervised` or use `torchvision` backbones.","error":"ModuleNotFoundError: No module named 'lightly.models.resnet'"},{"fix":"Ensure both your model and your input data are on the same device. For example, after defining `model = MoCo(...)`, move it to GPU with `model.to(device)` (where `device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')`). Similarly, move input tensors `x0.to(device), x1.to(device)` within your training loop.","cause":"A common PyTorch error indicating that some tensors are on the CPU while others are on the GPU, preventing operations between them. This often happens if a model or data is not explicitly moved to the correct device.","error":"RuntimeError: Expected all tensors to be on the same device, but found tensors on both cpu and cuda:0"},{"fix":"Review the initialization of your `lightly` model, loss function, or transforms. Ensure all required arguments are provided and that no step in their construction inadvertently results in a `None` value being assigned where an object is expected. For example, if a `LightlyDataset` or `collate_fn` cannot find data, it might behave unexpectedly.","cause":"This usually indicates that a variable you are trying to call as a function or method (e.g., `model(...)`) was assigned `None` because its initialization failed or returned `None`.","error":"TypeError: 'NoneType' object is not callable"}]}