Install & Compatibility
Where this runs
tested against v2.6.5 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.728s · 92.6MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 5.9s · import 0.418s · 89MB
105MB installed
● package 105MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
SummaryWriter
✓ from tensorboardX import SummaryWriter
This is the primary class for writing events to TensorBoard logs.
This quickstart demonstrates how to initialize a `SummaryWriter`, log scalar values over iterations, and log a PyTorch model graph. After running the script, a 'runs' directory will be created containing the event files. You then use the `tensorboard` command-line tool to launch the visualization server.
import torch
import numpy as np
from tensorboardX import SummaryWriter
# Create a writer instance, logs will be saved in 'runs/my_experiment'
writer = SummaryWriter('runs/my_experiment')
# Log scalar values
for i in range(100):
writer.add_scalar('training/loss', 100 - i * 0.5 + np.random.rand(), i)
writer.add_scalar('training/accuracy', 0.5 + i * 0.005 + np.random.rand() * 0.01, i)
# Log a Pytorch model graph (dummy model and input)
try:
import torch.nn as nn
class SimpleModel(nn.Module):
def __init__(self):
super().__init__()
self.linear = nn.Linear(10, 2)
def forward(self, x):
return self.linear(x)
dummy_input = torch.randn(1, 10)
model = SimpleModel()
writer.add_graph(model, dummy_input)
except ImportError:
print("PyTorch not installed, skipping add_graph example.")
# Close the writer to flush all pending events to disk
writer.close()
print("TensorBoardX logs written to 'runs/my_experiment'.")
print("To view these logs, run the following command in your terminal:")
print(" tensorboard --logdir=runs")
Debug
Known issues
breakingThe `protobuf` dependency has undergone several version changes. Version 2.6.5 requires `protobuf>=5.29.6`. Earlier versions required `>=3.20`. Ensure your `protobuf` version is compatible with your `tensorboardX` installation to avoid `TypeError` or `ImportError` issues.fixCheck the `tensorboardX` PyPI page or `pyproject.toml` for the exact `protobuf` requirement for your installed version and upgrade/downgrade `protobuf` accordingly (e.g., `pip install protobuf==X.Y.Z`).
affects: <2.6.5
gotchaTensorBoardX only generates the log files; the `tensorboard` package itself must be installed separately to run the visualization server. Without it, you cannot view the generated logs.fixInstall `tensorboard` alongside `tensorboardx`: `pip install tensorboardx tensorboard`. Then run the server with `tensorboard --logdir=<your_log_dir>`.
affects: All versions
gotchaLogging performance can be an issue, especially when displaying many experiments (3+) or logging high-resolution data (images, large histograms) with many points. While logging is cheap, displaying can be expensive and slow down TensorBoard.fixConsider reducing the frequency of logging expensive data types (images, histograms), grouping related scalars using `writer.add_scalars`, or using fewer experiments in the TensorBoard view.
affects: All versions
gotchaWhen logging PyTorch scalar tensors, you must extract the Python scalar value using `.item()` before passing it to `add_scalar()`, otherwise `tensorboardX` may complain.fixInstead of `writer.add_scalar('tag', torch_tensor, iteration)`, use `writer.add_scalar('tag', torch_tensor.item(), iteration)`. affects: All versions
deprecatedThe `add_audio()` function was significantly optimized (200x speedup) starting from version 2.1, but this requires the `soundfile` package to be installed.fixFor optimal performance with `add_audio()`, ensure `tensorboardX` is v2.1 or newer and install `soundfile`: `pip install soundfile`.
affects: <2.1
breakingFrom `tensorboardX` v2.1, the `add_graph` function's underlying implementation was delegated to `torch.utils.tensorboard`. While the API might remain similar, internal behavior and potential compatibility nuances with specific PyTorch versions could change.fixIf encountering issues with `add_graph` on older `tensorboardX` versions, consider upgrading to v2.1 or newer and ensuring PyTorch compatibility. Consult `torch.utils.tensorboard` documentation for specific graph tracing requirements.
affects: <2.1
gotchaImporting `tensorboardX` after `tensorboard` (specifically `from tensorboard import main as tb`) in the same Python session can lead to `TypeError: Couldn't build proto file into descriptor pool!` due to conflicts in protobuf descriptor registration.fixAvoid importing `tensorboardX` after `tensorboard` in the same session. If both are needed, ensure `tensorboardX` is imported first, or consider running them in separate processes if strict isolation is required.
affects: All versions (observed in 1.8 and later)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'tensorboardx'
The tensorboardx library has not been installed in the current Python environment.
fixpip install tensorboardx
ModuleNotFoundError: No module named 'tensorboardX'
The import statement uses incorrect capitalization for the library name (capital 'X' instead of lowercase 'x').
fixfrom tensorboardx import SummaryWriter
TypeError: add_graph() missing 1 required positional argument: 'input_to_model'
The add_graph method requires an example input tensor to correctly trace and visualize the PyTorch model's computational graph.
fixwriter.add_graph(model, input_to_model=torch.randn(1, *input_shape))
TypeError: can't convert CUDA tensor to numpy. Use .cpu() to move the tensor to CPU first.
You are attempting to convert a PyTorch tensor residing on a CUDA device directly to a NumPy array, which is not supported; it must first be moved to the CPU.
fixtensor_on_cpu_numpy = tensor_on_cuda.cpu().numpy()
Upgrade
Version history
2.6.5latest on PyPI · released Apr 3, 2026
Audit
Dependencies
numpyrequiredCore dependency for data handling.
packagingrequiredUsed for version parsing and compatibility.
protobufrequiredRequired for serializing data into TensorBoard's event file format. Version >=5.29.6 is required for 2.6.5.
crc32coptionalOptional, provides speedup for CRC32C checksum calculations.
soundfileoptionalOptional, significantly speeds up the `add_audio()` function (200x speedup from v2.1).
tensorboardoptionalRequired to run the TensorBoard web server to view the logs generated by TensorBoardX.