Tensorboard

Visualize ML training metrics and debug models with Google's toolkit

✨ The solution you've been looking for

Verified
Tested and verified by our team
16036 Stars

Visualize training metrics, debug models with histograms, compare experiments, visualize model graphs, and profile performance with TensorBoard - Google's ML visualization toolkit

tensorboard ml-visualization training-metrics model-debugging pytorch tensorflow experiment-tracking performance-profiling
Repository

See It In Action

Interactive preview & real-world examples

Live Demo
Skill Demo Animation

AI Conversation Simulator

See how users interact with this skill

User Prompt

Help me set up TensorBoard to visualize my PyTorch training metrics including loss, accuracy, and learning rate over epochs

Skill Processing

Analyzing request...

Agent Response

Complete setup with SummaryWriter logging scalars, properly organized metric groups, and TensorBoard dashboard showing training progress

Quick Start (3 Steps)

Get up and running in minutes

1

Install

claude-code skill install tensorboard

claude-code skill install tensorboard
2

Config

3

First Trigger

@tensorboard help

Commands

CommandDescriptionRequired Args
@tensorboard training-visualizationTrack loss and accuracy curves during model training to monitor convergence and detect overfittingNone
@tensorboard model-debuggingDebug neural networks by visualizing weight distributions, gradients, and activation patternsNone
@tensorboard experiment-comparisonCompare multiple training runs with different hyperparameters to identify optimal configurationsNone

Typical Use Cases

Training Visualization

Track loss and accuracy curves during model training to monitor convergence and detect overfitting

Model Debugging

Debug neural networks by visualizing weight distributions, gradients, and activation patterns

Experiment Comparison

Compare multiple training runs with different hyperparameters to identify optimal configurations

Overview

TensorBoard: Visualization Toolkit for ML

When to Use This Skill

Use TensorBoard when you need to:

  • Visualize training metrics like loss and accuracy over time
  • Debug models with histograms and distributions
  • Compare experiments across multiple runs
  • Visualize model graphs and architecture
  • Project embeddings to lower dimensions (t-SNE, PCA)
  • Track hyperparameter experiments
  • Profile performance and identify bottlenecks
  • Visualize images and text during training

Users: 20M+ downloads/year | GitHub Stars: 27k+ | License: Apache 2.0

Installation

 1# Install TensorBoard
 2pip install tensorboard
 3
 4# PyTorch integration
 5pip install torch torchvision tensorboard
 6
 7# TensorFlow integration (TensorBoard included)
 8pip install tensorflow
 9
10# Launch TensorBoard
11tensorboard --logdir=runs
12# Access at http://localhost:6006

Quick Start

PyTorch

 1from torch.utils.tensorboard import SummaryWriter
 2
 3# Create writer
 4writer = SummaryWriter('runs/experiment_1')
 5
 6# Training loop
 7for epoch in range(10):
 8    train_loss = train_epoch()
 9    val_acc = validate()
10
11    # Log metrics
12    writer.add_scalar('Loss/train', train_loss, epoch)
13    writer.add_scalar('Accuracy/val', val_acc, epoch)
14
15# Close writer
16writer.close()
17
18# Launch: tensorboard --logdir=runs

TensorFlow/Keras

 1import tensorflow as tf
 2
 3# Create callback
 4tensorboard_callback = tf.keras.callbacks.TensorBoard(
 5    log_dir='logs/fit',
 6    histogram_freq=1
 7)
 8
 9# Train model
10model.fit(
11    x_train, y_train,
12    epochs=10,
13    validation_data=(x_val, y_val),
14    callbacks=[tensorboard_callback]
15)
16
17# Launch: tensorboard --logdir=logs

Core Concepts

1. SummaryWriter (PyTorch)

 1from torch.utils.tensorboard import SummaryWriter
 2
 3# Default directory: runs/CURRENT_DATETIME
 4writer = SummaryWriter()
 5
 6# Custom directory
 7writer = SummaryWriter('runs/experiment_1')
 8
 9# Custom comment (appended to default directory)
10writer = SummaryWriter(comment='baseline')
11
12# Log data
13writer.add_scalar('Loss/train', 0.5, step=0)
14writer.add_scalar('Loss/train', 0.3, step=1)
15
16# Flush and close
17writer.flush()
18writer.close()

2. Logging Scalars

 1# PyTorch
 2from torch.utils.tensorboard import SummaryWriter
 3writer = SummaryWriter()
 4
 5for epoch in range(100):
 6    train_loss = train()
 7    val_loss = validate()
 8
 9    # Log individual metrics
10    writer.add_scalar('Loss/train', train_loss, epoch)
11    writer.add_scalar('Loss/val', val_loss, epoch)
12    writer.add_scalar('Accuracy/train', train_acc, epoch)
13    writer.add_scalar('Accuracy/val', val_acc, epoch)
14
15    # Learning rate
16    lr = optimizer.param_groups[0]['lr']
17    writer.add_scalar('Learning_rate', lr, epoch)
18
19writer.close()
 1# TensorFlow
 2import tensorflow as tf
 3
 4train_summary_writer = tf.summary.create_file_writer('logs/train')
 5val_summary_writer = tf.summary.create_file_writer('logs/val')
 6
 7for epoch in range(100):
 8    with train_summary_writer.as_default():
 9        tf.summary.scalar('loss', train_loss, step=epoch)
10        tf.summary.scalar('accuracy', train_acc, step=epoch)
11
12    with val_summary_writer.as_default():
13        tf.summary.scalar('loss', val_loss, step=epoch)
14        tf.summary.scalar('accuracy', val_acc, step=epoch)

3. Logging Multiple Scalars

 1# PyTorch: Group related metrics
 2writer.add_scalars('Loss', {
 3    'train': train_loss,
 4    'validation': val_loss,
 5    'test': test_loss
 6}, epoch)
 7
 8writer.add_scalars('Metrics', {
 9    'accuracy': accuracy,
10    'precision': precision,
11    'recall': recall,
12    'f1': f1_score
13}, epoch)

4. Logging Images

 1# PyTorch
 2import torch
 3from torchvision.utils import make_grid
 4
 5# Single image
 6writer.add_image('Input/sample', img_tensor, epoch)
 7
 8# Multiple images as grid
 9img_grid = make_grid(images[:64], nrow=8)
10writer.add_image('Batch/inputs', img_grid, epoch)
11
12# Predictions visualization
13pred_grid = make_grid(predictions[:16], nrow=4)
14writer.add_image('Predictions', pred_grid, epoch)
1# TensorFlow
2import tensorflow as tf
3
4with file_writer.as_default():
5    # Encode images as PNG
6    tf.summary.image('Training samples', images, step=epoch, max_outputs=25)

5. Logging Histograms

 1# PyTorch: Track weight distributions
 2for name, param in model.named_parameters():
 3    writer.add_histogram(name, param, epoch)
 4
 5    # Track gradients
 6    if param.grad is not None:
 7        writer.add_histogram(f'{name}.grad', param.grad, epoch)
 8
 9# Track activations
10writer.add_histogram('Activations/relu1', activations, epoch)
1# TensorFlow
2with file_writer.as_default():
3    tf.summary.histogram('weights/layer1', layer1.kernel, step=epoch)
4    tf.summary.histogram('activations/relu1', activations, step=epoch)

6. Logging Model Graph

1# PyTorch
2import torch
3
4model = MyModel()
5dummy_input = torch.randn(1, 3, 224, 224)
6
7writer.add_graph(model, dummy_input)
8writer.close()
1# TensorFlow (automatic with Keras)
2tensorboard_callback = tf.keras.callbacks.TensorBoard(
3    log_dir='logs',
4    write_graph=True
5)
6
7model.fit(x, y, callbacks=[tensorboard_callback])

Advanced Features

Embedding Projector

Visualize high-dimensional data (embeddings, features) in 2D/3D.

 1import torch
 2from torch.utils.tensorboard import SummaryWriter
 3
 4# Get embeddings (e.g., word embeddings, image features)
 5embeddings = model.get_embeddings(data)  # Shape: (N, embedding_dim)
 6
 7# Metadata (labels for each point)
 8metadata = ['class_1', 'class_2', 'class_1', ...]
 9
10# Images (optional, for image embeddings)
11label_images = torch.stack([img1, img2, img3, ...])
12
13# Log to TensorBoard
14writer.add_embedding(
15    embeddings,
16    metadata=metadata,
17    label_img=label_images,
18    global_step=epoch
19)

In TensorBoard:

  • Navigate to “Projector” tab
  • Choose PCA, t-SNE, or UMAP visualization
  • Search, filter, and explore clusters

Hyperparameter Tuning

 1from torch.utils.tensorboard import SummaryWriter
 2
 3# Try different hyperparameters
 4for lr in [0.001, 0.01, 0.1]:
 5    for batch_size in [16, 32, 64]:
 6        # Create unique run directory
 7        writer = SummaryWriter(f'runs/lr{lr}_bs{batch_size}')
 8
 9        # Log hyperparameters
10        writer.add_hparams(
11            {'lr': lr, 'batch_size': batch_size},
12            {'hparam/accuracy': final_acc, 'hparam/loss': final_loss}
13        )
14
15        # Train and log
16        for epoch in range(10):
17            loss = train(lr, batch_size)
18            writer.add_scalar('Loss/train', loss, epoch)
19
20        writer.close()
21
22# Compare in TensorBoard's "HParams" tab

Text Logging

 1# PyTorch: Log text (e.g., model predictions, summaries)
 2writer.add_text('Predictions', f'Epoch {epoch}: {predictions}', epoch)
 3writer.add_text('Config', str(config), 0)
 4
 5# Log markdown tables
 6markdown_table = """
 7| Metric | Value |
 8|--------|-------|
 9| Accuracy | 0.95 |
10| F1 Score | 0.93 |
11"""
12writer.add_text('Results', markdown_table, epoch)

PR Curves

Precision-Recall curves for classification.

 1from torch.utils.tensorboard import SummaryWriter
 2
 3# Get predictions and labels
 4predictions = model(test_data)  # Shape: (N, num_classes)
 5labels = test_labels  # Shape: (N,)
 6
 7# Log PR curve for each class
 8for i in range(num_classes):
 9    writer.add_pr_curve(
10        f'PR_curve/class_{i}',
11        labels == i,
12        predictions[:, i],
13        global_step=epoch
14    )

Integration Examples

PyTorch Training Loop

 1import torch
 2import torch.nn as nn
 3from torch.utils.tensorboard import SummaryWriter
 4
 5# Setup
 6writer = SummaryWriter('runs/resnet_experiment')
 7model = ResNet50()
 8optimizer = torch.optim.Adam(model.parameters(), lr=0.001)
 9criterion = nn.CrossEntropyLoss()
10
11# Log model graph
12dummy_input = torch.randn(1, 3, 224, 224)
13writer.add_graph(model, dummy_input)
14
15# Training loop
16for epoch in range(50):
17    model.train()
18    train_loss = 0.0
19    train_correct = 0
20
21    for batch_idx, (data, target) in enumerate(train_loader):
22        optimizer.zero_grad()
23        output = model(data)
24        loss = criterion(output, target)
25        loss.backward()
26        optimizer.step()
27
28        train_loss += loss.item()
29        pred = output.argmax(dim=1)
30        train_correct += pred.eq(target).sum().item()
31
32        # Log batch metrics (every 100 batches)
33        if batch_idx % 100 == 0:
34            global_step = epoch * len(train_loader) + batch_idx
35            writer.add_scalar('Loss/train_batch', loss.item(), global_step)
36
37    # Epoch metrics
38    train_loss /= len(train_loader)
39    train_acc = train_correct / len(train_loader.dataset)
40
41    # Validation
42    model.eval()
43    val_loss = 0.0
44    val_correct = 0
45
46    with torch.no_grad():
47        for data, target in val_loader:
48            output = model(data)
49            val_loss += criterion(output, target).item()
50            pred = output.argmax(dim=1)
51            val_correct += pred.eq(target).sum().item()
52
53    val_loss /= len(val_loader)
54    val_acc = val_correct / len(val_loader.dataset)
55
56    # Log epoch metrics
57    writer.add_scalars('Loss', {'train': train_loss, 'val': val_loss}, epoch)
58    writer.add_scalars('Accuracy', {'train': train_acc, 'val': val_acc}, epoch)
59
60    # Log learning rate
61    writer.add_scalar('Learning_rate', optimizer.param_groups[0]['lr'], epoch)
62
63    # Log histograms (every 5 epochs)
64    if epoch % 5 == 0:
65        for name, param in model.named_parameters():
66            writer.add_histogram(name, param, epoch)
67
68    # Log sample predictions
69    if epoch % 10 == 0:
70        sample_images = data[:8]
71        writer.add_image('Sample_inputs', make_grid(sample_images), epoch)
72
73writer.close()

TensorFlow/Keras Training

 1import tensorflow as tf
 2
 3# Define model
 4model = tf.keras.models.Sequential([
 5    tf.keras.layers.Conv2D(32, 3, activation='relu', input_shape=(28, 28, 1)),
 6    tf.keras.layers.MaxPooling2D(),
 7    tf.keras.layers.Flatten(),
 8    tf.keras.layers.Dense(128, activation='relu'),
 9    tf.keras.layers.Dense(10, activation='softmax')
10])
11
12model.compile(
13    optimizer='adam',
14    loss='sparse_categorical_crossentropy',
15    metrics=['accuracy']
16)
17
18# TensorBoard callback
19tensorboard_callback = tf.keras.callbacks.TensorBoard(
20    log_dir='logs/fit',
21    histogram_freq=1,          # Log histograms every epoch
22    write_graph=True,          # Visualize model graph
23    write_images=True,         # Visualize weights as images
24    update_freq='epoch',       # Log metrics every epoch
25    profile_batch='500,520',   # Profile batches 500-520
26    embeddings_freq=1          # Log embeddings every epoch
27)
28
29# Train
30model.fit(
31    x_train, y_train,
32    epochs=10,
33    validation_data=(x_val, y_val),
34    callbacks=[tensorboard_callback]
35)

Comparing Experiments

Multiple Runs

1# Run experiments with different configs
2python train.py --lr 0.001 --logdir runs/exp1
3python train.py --lr 0.01 --logdir runs/exp2
4python train.py --lr 0.1 --logdir runs/exp3
5
6# View all runs together
7tensorboard --logdir=runs

In TensorBoard:

  • All runs appear in the same dashboard
  • Toggle runs on/off for comparison
  • Use regex to filter run names
  • Overlay charts to compare metrics

Organizing Experiments

 1# Hierarchical organization
 2runs/
 3├── baseline/
 4   ├── run_1/
 5   └── run_2/
 6├── improved/
 7   ├── run_1/
 8   └── run_2/
 9└── final/
10    └── run_1/
11
12# Log with hierarchy
13writer = SummaryWriter('runs/baseline/run_1')

Best Practices

1. Use Descriptive Run Names

1# ✅ Good: Descriptive names
2from datetime import datetime
3timestamp = datetime.now().strftime('%Y%m%d_%H%M%S')
4writer = SummaryWriter(f'runs/resnet50_lr0.001_bs32_{timestamp}')
5
6# ❌ Bad: Auto-generated names
7writer = SummaryWriter()  # Creates runs/Jan01_12-34-56_hostname
1# ✅ Good: Grouped metrics
2writer.add_scalar('Loss/train', train_loss, step)
3writer.add_scalar('Loss/val', val_loss, step)
4writer.add_scalar('Accuracy/train', train_acc, step)
5writer.add_scalar('Accuracy/val', val_acc, step)
6
7# ❌ Bad: Flat namespace
8writer.add_scalar('train_loss', train_loss, step)
9writer.add_scalar('val_loss', val_loss, step)

3. Log Regularly but Not Too Often

 1# ✅ Good: Log epoch metrics always, batch metrics occasionally
 2for epoch in range(100):
 3    for batch_idx, (data, target) in enumerate(train_loader):
 4        loss = train_step(data, target)
 5
 6        # Log every 100 batches
 7        if batch_idx % 100 == 0:
 8            writer.add_scalar('Loss/batch', loss, global_step)
 9
10    # Always log epoch metrics
11    writer.add_scalar('Loss/epoch', epoch_loss, epoch)
12
13# ❌ Bad: Log every batch (creates huge log files)
14for batch in train_loader:
15    writer.add_scalar('Loss', loss, step)  # Too frequent

4. Close Writer When Done

 1# ✅ Good: Use context manager
 2with SummaryWriter('runs/exp1') as writer:
 3    for epoch in range(10):
 4        writer.add_scalar('Loss', loss, epoch)
 5# Automatically closes
 6
 7# Or manually
 8writer = SummaryWriter('runs/exp1')
 9# ... logging ...
10writer.close()

5. Use Separate Writers for Train/Val

1# ✅ Good: Separate log directories
2train_writer = SummaryWriter('runs/exp1/train')
3val_writer = SummaryWriter('runs/exp1/val')
4
5train_writer.add_scalar('loss', train_loss, epoch)
6val_writer.add_scalar('loss', val_loss, epoch)

Performance Profiling

TensorFlow Profiler

 1# Enable profiling
 2tensorboard_callback = tf.keras.callbacks.TensorBoard(
 3    log_dir='logs',
 4    profile_batch='10,20'  # Profile batches 10-20
 5)
 6
 7model.fit(x, y, callbacks=[tensorboard_callback])
 8
 9# View in TensorBoard Profile tab
10# Shows: GPU utilization, kernel stats, memory usage, bottlenecks

PyTorch Profiler

 1import torch.profiler as profiler
 2
 3with profiler.profile(
 4    activities=[
 5        profiler.ProfilerActivity.CPU,
 6        profiler.ProfilerActivity.CUDA
 7    ],
 8    on_trace_ready=torch.profiler.tensorboard_trace_handler('./runs/profiler'),
 9    record_shapes=True,
10    with_stack=True
11) as prof:
12    for batch in train_loader:
13        loss = train_step(batch)
14        prof.step()
15
16# View in TensorBoard Profile tab

Resources

See Also

  • references/visualization.md - Comprehensive visualization guide
  • references/profiling.md - Performance profiling patterns
  • references/integrations.md - Framework-specific integration examples

What Users Are Saying

Real feedback from the community

Environment Matrix

Dependencies

tensorboard (latest)
torch (for PyTorch integration)
tensorflow (includes TensorBoard)

Framework Support

PyTorch ✓ (recommended) TensorFlow/Keras ✓ JAX ✓ Scikit-learn ✓

Context Window

Token Usage ~3K-8K tokens for typical training loop integration

Security & Privacy

Information

Author
davila7
Updated
2026-01-30
Category
debugging