lightning-metrics-tui 0.2.0

TensorBoard-like terminal monitor for PyTorch Lightning metrics, CSVLogger runs, and live run comparison.

ltui - terminal TensorBoard for PyTorch Lightning metrics

Monitor PyTorch Lightning training runs directly over SSH or inside tmux. No browser, no TensorBoard server, no port forwarding.

pipx install lightning-metrics-tui
ltui --demo

For your own Lightning logs:

ltui ./lightning_logs

Why ltui?

ltui is a TensorBoard-like terminal monitor for PyTorch Lightning metrics. It is built for remote training sessions where opening a browser, starting a TensorBoard server, or forwarding ports is friction.

Use it to inspect Lightning CSVLogger runs, compare versions, group train/validation metrics, smooth noisy curves, inspect run configs, and navigate everything from the terminal.

Quick start

pipx install lightning-metrics-tui
ltui --demo

For one-shot use without a persistent install:

pipx run --spec lightning-metrics-tui ltui --demo

The command remains ltui. The install package is lightning-metrics-tui, and the Python module remains ltui.

Try the demo

ltui --demo

The demo opens bundled Lightning-style CSVLogger logs with three versions, training and validation loss, accuracy, learning rate, and hparams.yaml files. The demo data is copied to a temporary directory before launch.

From a source checkout, the same example data is available at:

ltui examples/lightning_logs

Usage with existing Lightning logs

Point ltui at any directory containing Lightning logs:

ltui /path/to/log/root

Common examples:

ltui ./outputs
ltui ./lightning_logs
ltui /data/experiments/stage1

On startup, ltui recursively discovers supported run directories, selects the latest modified run by default, and chooses a loss metric when one is available. The preferred x-axis is step, then epoch, then row index. Press a to toggle between step and epoch mode.

Usage with PyTorch Lightning CSVLogger

Existing Lightning CSVLogger runs work without changing your training code. Every discovered metrics.csv is treated as one selectable run/version.

Supported layouts include:

lightning_logs/version_0/metrics.csv
run_a/version_0/metrics.csv
run_a/lightning_logs/version_0/metrics.csv
experiments/group_1/run_a/lightning_logs/version_3/metrics.csv

For native metrics.csv files, train/validation grouping uses the standard prefixes:

train_
val_

Examples:

train_loss + val_loss -> loss
train_recon_loss + val_recon_loss -> recon_loss
train_kl + val_kl -> kl

Lightning step/epoch suffixes are handled as part of the same family, so train_loss_step, train_loss_epoch, and val_loss appear as loss.

Usage with LtuiLogger

LtuiLogger is an optional PyTorch Lightning logger for new runs. It writes a small manifest, one narrow CSV file per metric series, optional image folders, and hyperparameters as JSON.

Install the optional logger dependencies in your training environment:

python -m pip install "lightning-metrics-tui[logger]"

Use it with Lightning:

from lightning.pytorch import Trainer
from ltui.lightning import LtuiLogger

logger = LtuiLogger(
    save_dir="outputs",
    name="stage1",
)

trainer = Trainer(logger=logger)

Path-style metric names create a hierarchy in the metric selector and multiplot view:

self.log("train/loss/kl", train_kl)
self.log("val/loss/kl", val_kl)
self.log("train/loss/recon", train_recon)
self.log("val/loss/recon", val_recon)

The logger also accepts train_ and val_ style names with the default prefixes, so simple metric names like train_loss and val_loss remain grouped as loss.

Images can be logged with the same path-style hierarchy:

logger.log_image("train/recon/sample", image, step=global_step, epoch=current_epoch)
logger.experiment.add_image("val/recon/sample", image_tensor, global_step=global_step)

Press i in the TUI to choose an image stream. Image viewing launches feh when it is installed.

Features

• Live terminal monitoring for PyTorch Lightning runs
• Lightning CSVLogger metrics.csv compatibility
• Optional LtuiLogger for structured metric and image logs
• Train/validation metric grouping
• Grouped multiplot pages for sibling metrics
• Multi-run comparison with color-coded legends
• Step and epoch x-axis modes with Lightning-friendly validation alignment
• Log scaling and EMA smoothing
• YAML config inspection for runs with a unique config file
• Keyboard-first selectors with fuzzy search

Why use ltui instead of TensorBoard?

Use ltui when you:

• train on a remote machine over SSH
• work inside tmux
• do not want to forward ports
• want to inspect CSVLogger-compatible metrics quickly
• want terminal-native run comparison
• want a lightweight monitor without starting a TensorBoard server

TensorBoard is still the broader tool for full experiment dashboards, plugin views, embeddings, and richer browser-based inspection. ltui focuses on fast scalar metric monitoring in the terminal.

How is this different from generic terminal plotters?

Generic terminal plotters can display scalar data, TensorBoard logs, or CSV files. ltui is focused on PyTorch Lightning training workflows: Lightning-style log directories, CSVLogger-compatible metrics, train/validation metric grouping, run comparison, smoothing, config inspection, and terminal-native navigation.

Installation

Recommended CLI install:

pipx install lightning-metrics-tui

Normal pip install:

python -m pip install lightning-metrics-tui

Optional logger dependencies:

python -m pip install "lightning-metrics-tui[logger]"

The TUI itself does not require PyTorch Lightning.

Controls

Key	Action
r	Open run/version selector
c	Open config viewer for runs with a unique YAML config
m	Open metric selector
i	Open image selector and launch feh for the selected image stream
/	Fuzzy search inside selector
arrow keys	Navigate selector or selected plot in multiplot mode; left/right jump between models in run/config selectors
space	Toggle selection in selector, open multiplot on main screen
enter	Apply selector, focus selected plot in multiplot mode
escape	Clear plot selection in multiplot mode
n	Next selected metric/family, or next page in multiplot mode
p	Previous selected metric/family, or previous page in multiplot mode
a	Toggle x-axis between step and epoch
d	Toggle dark/light plot theme
s	Toggle smoothing
x	Toggle log-x
y	Toggle log-y
q	Quit

Development

python -m pip install -e ".[dev]"
pytest
python -m build

Changelog / release notes

See CHANGELOG.md.