lightning-hydra-template: A PyTorch Lightning and Hydra Project Template

Reducing Boilerplate in Deep Learning Research

lightning-hydra-template addresses the overhead that accumulates when starting a new deep learning project. Setting up training loops, handling accelerator configuration, wiring experiment loggers, and managing hyperparameter files are all tasks that repeat across projects but contribute nothing specific to the research question. The template packages those patterns once so new projects can start from a consistent baseline.

The README identifies three reasons to use it: it saves boilerplate (models, datasets, tasks, experiments, and accelerator configurations are pluggable), it serves an educational purpose (the code is thoroughly commented), and it provides reusable MLOps utilities and configuration snippets.

The template is an unofficial community project, not an official product of PyTorch Lightning or Hydra. The README notes this explicitly. This matters for teams that need official support contracts or guaranteed compatibility with specific Lightning or Hydra releases.

Project Structure: The Config Directory and Source Layout

The directory structure follows a consistent pattern. The configs/ directory is the central location for all Hydra configurations and is divided into subdirectories for each configurable component.

├── configs                   <- Hydra configs
│   ├── callbacks                <- Callbacks configs
│   ├── data                     <- Data configs
│   ├── debug                    <- Debugging configs
│   ├── experiment               <- Experiment configs
│   ├── extras                   <- Extra utilities configs
│   ├── hparams_search           <- Hyperparameter search configs
│   ├── hydra                    <- Hydra configs
│   ├── local                    <- Local configs
│   ├── logger                   <- Logger configs

The src/ directory contains training and evaluation code. The tests/ directory contains smoke tests. The scripts/ directory contains utility scripts. The data/ and logs/ directories store datasets and output respectively. The notebooks/ directory is available for Jupyter work.

The .env.example file shows the pattern for environment-specific configuration: rename it to .env (which is excluded from version control by default) and the training script loads it automatically. Hydra configs can reference environment variables with the syntax `${oc.env:MY_VAR}`, which keeps paths and secrets out of the committed configuration files.

Quickstart: Cloning, Installing, and Running the MNIST Example

The README provides a quickstart sequence. Clone the repository, optionally create a conda environment, install PyTorch according to the official instructions for your hardware, then install the remaining requirements.

git clone https://github.com/ashleve/lightning-hydra-template
cd lightning-hydra-template
conda create -n myenv python=3.9
conda activate myenv
pip install -r requirements.txt

The requirements.txt pins the following key dependencies: torch>=2.0.0, torchvision>=0.15.0, lightning>=2.0.0, hydra-core==1.3.2, hydra-colorlog==1.2.0, and hydra-optuna-sweeper==1.2.0. Hydra is pinned to 1.3.2 while Lightning and PyTorch take a minimum version constraint.

The template ships with an MNIST classification example. Running the training script starts this example.

python src/train.py

For experiment tracking, the requirements.txt lists W&B, Neptune, MLflow, and Comet as commented-out optional dependencies alongside the always-installed CSVLogger and Tensorboard paths. To activate W&B logging, configure the project name in the logger config.

wandb:
  project: "your_project_name"
  entity: "your_wandb_team_name"

Hydra's Command-Line Config Override System

The main technical advantage of using Hydra in this template is the ability to override any configuration parameter from the command line without modifying files. The README shows this working for training hyperparameters.

python train.py trainer.max_epochs=20 model.optimizer.lr=1e-4

New parameters can be added inline with the `+` prefix.

python train.py +model.new_param="owo"

The same mechanism handles accelerator selection. Switching between CPU, single GPU, and multi-GPU DDP training requires only a trainer argument change rather than code modifications.

python train.py trainer=cpu
python train.py trainer=gpu
python train.py trainer=ddp trainer.devices=4

Training with mixed precision adds a precision flag without touching the model code.

python train.py trainer=gpu +trainer.precision=16

The configs/experiment/ directory is where versioned experiment configurations live. Each experiment file overrides the relevant hyperparameters for a specific run, creating a git-trackable record of what was trained without duplicating code. This is the primary workflow the template is designed around: define a baseline config, create experiment overrides, and run them with a single command.

Four Reasons the README Says Not to Use It

The README dedicates a section to reasons not to use the template, which is worth reading carefully before committing to it.

First, Lightning and Hydra are still evolving. The README notes that because both frameworks integrate many libraries, things break from time to time. The README links to a page listing currently known bugs.

Second, the template is not adjusted for data engineering. It is designed for training on ready-to-use data. If your workflow involves data pipelines where preprocessing steps depend on each other, the template's configuration structure does not map to those dependencies.

Third, the configuration is overfitted to a simple use case. Adapting it for Lightning Fabric or other non-standard Lightning setups requires effort. The template assumes a straightforward Lightning training loop.

Fourth, it might not support your workflow. The README specifically calls out that you cannot resume a Hydra-based multirun or hyperparameter search if it was interrupted. Additionally, the README includes a specific warning about DDP mode: 'Currently there are problems with DDP mode.' Teams planning to train across multiple GPUs with DDP should check the linked issue before relying on that configuration.

lightning-hydra-template vs. Cookiecutter Data Science

Cookiecutter Data Science is a project template for data science work that organises the full pipeline from raw data to reports and models. The scope difference from lightning-hydra-template is significant: Cookiecutter Data Science covers data acquisition, preprocessing, feature engineering, modelling, and reporting as separate stages. lightning-hydra-template focuses on the training loop and experiment configuration, assuming data is already preprocessed and ready to load.

For research that starts from a public benchmark dataset and focuses on model architecture or training algorithm experimentation, lightning-hydra-template's narrower scope is an advantage because the configuration system is specifically tuned for that use case. For projects where data collection, cleaning, and feature engineering are major concerns, Cookiecutter Data Science's broader structure is more appropriate.

A second difference is the configuration system. Cookiecutter Data Science does not prescribe a configuration management approach. lightning-hydra-template requires Hydra, which has its own learning curve, particularly around how Hydra manages multirun sweeps and output directories.

Licence, Maintenance Status, and Known Issues

The repository does not list a named licence in the metadata. The README does not include a licence section. Before using the template as the basis for a commercial project, teams should verify the licence status directly from the repository, as the metadata reports it as unknown.

The last push to the repository was on 2026-06-11, showing recent activity. The formal releases are older: v2.0.3 was published in September 2023, v2.0.2 in May 2023, and v2.0.1 in March 2023. The gap between the last tagged release and the most recent commit is over three years. This suggests ongoing fixes are applied to the main branch without corresponding tagged releases.

The repository uses GitHub Actions for continuous integration (workflows for tests and code quality). The pyproject.toml configures pytest with strict markers, color output, and a testpaths setting pointing to tests/. Pre-commit hooks are included via the .pre-commit-config.yaml file.

The template uses rootutils for standardizing the project root setup and rich for formatted terminal output during training. These are listed in requirements.txt as non-commented dependencies alongside pytest.

Editorial conclusion

lightning-hydra-template is the right starting point for deep learning researchers who work with ready-to-use datasets and want to run controlled experiments with hyperparameter overrides from the command line. It is the wrong choice for teams building data pipelines that depend on each other, for projects that need to resume interrupted Hydra multiruns, or for any use case where the configuration setup would need significant restructuring beyond simple Lightning training. The template ships with an MNIST example at src/train.py; run that first to confirm the dependencies install cleanly on your hardware before adapting the template to your own model and data.

Frequently asked questions

Official sources

1. ashleve/lightning-hydra-template on GitHub
2. Issues
3. README
4. Releases