tfevents-reader

Fast, zero-dependency reader for TensorBoard tfevents files.

Extract scalar metrics from TensorBoard event files without installing TensorBoard, TensorFlow, or PyTorch.

Perfect for quick inspection of training runs, hyperparameter sweeps, or when you just need the numbers without the full TensorBoard stack.

Features

• Zero dependencies — pure Python + stdlib
• Reads both old (simple_value) and modern (tensor / PyTorch Lightning) scalar formats
• Groups results by top-level experiment directory (great for ablation studies)
• Multiple output formats: human-readable, JSON, CSV
• Tag filtering, detailed step inspection, NaN detection
• Extremely fast even on large runs

Installation

With pipx (recommended)

pipx install git+https://github.com/lostadi/tfevents-reader.git
# or from a local checkout
pipx install /path/to/tfevents-reader

With uv / pip

uv tool install git+https://github.com/lostadi/tfevents-reader.git
# or
pip install git+https://github.com/lostadi/tfevents-reader.git

Usage

# Basic summary (first + last value per tag)
read-tfevents ~/runs/my_experiment

# EVERY single recorded value (step, tag, value) — full raw data
read-tfevents ~/runs/ --full

# Filter to only loss-related tags + show every single recording
read-tfevents ~/runs/ --full --tag loss

# JSON output (full data)
read-tfevents ~/runs/ --json > results.json

# Export EVERYTHING to CSV (best for pandas / further analysis)
read-tfevents ~/runs/ --csv > all_scalars.csv

# Only show tags containing "loss" (summary mode)
read-tfevents ~/runs/ --tag loss

# Show first 5 + last 5 steps per tag
read-tfevents ~/runs/ --detailed

Example output

======================================================================
  gpt2-medium-lr3e-4  (14 tags, 18420 total scalars)
======================================================================

  train/loss
    steps=  1240   first=     10.2345   last=      2.8712

  val/loss
    steps=   310   first=      8.9123   last=      3.0145   *** 2 NaN(s) ***

  train/accuracy
    steps=  1240   first=      0.0123   last=      0.8745

Why this exists

TensorBoard is great, but sometimes you just want to quickly answer:

• "What was the final validation loss?"
• "Did any runs produce NaNs?"
• "Let me dump all the scalars into a DataFrame / JSON for analysis"

This tool gives you that in < 1 second with zero heavy dependencies.

Development

git clone https://github.com/lostadi/tfevents-reader.git
cd tfevents-reader

# Using uv (recommended)
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"

# Run linter + formatter
ruff check .
ruff format .

# Run tests
pytest

# Type check
mypy src

Project structure

src/tfevents_reader/
├── __init__.py      # package metadata
├── core.py          # TFRecord + protobuf parsing logic (library usable)
├── cli.py           # rich command-line interface
└── __main__.py      # python -m tfevents_reader support

The core module can be imported and used programmatically if you want to build tools on top of it.

License

MIT License — do whatever you want with it.

Contributing

Issues and PRs are very welcome! Especially:

• Support for more event types (histograms, images, text)
• Better handling of very large files
• Additional output formats (Parquet, etc.)

---

Made with ❤️ by Lee Ostadi for fast ML experiment inspection.