Install & Compatibility
Where this runs
tested against v2.21.0 · 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.95 runs
installs and imports cleanly · install 0.0s · import 0.002s · 147MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 7.2s · import 0.000s · 161MB
160MB installed
● package 160MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
SummaryWriter
✓ from tensorboard import program
✗ from torch.utils.tensorboard import SummaryWriter
This example demonstrates how to use `SummaryWriter` from `torch.utils.tensorboard` to log scalar values, creating event files in a timestamped directory. After running the script, you can launch TensorBoard from your terminal to visualize the logged data.
import datetime
from torch.utils.tensorboard import SummaryWriter
log_dir = "runs/" + datetime.datetime.now().strftime("%Y%m%d-%H%M%S")
writer = SummaryWriter(log_dir)
# Log a scalar value
for i in range(100):
writer.add_scalar('Loss/train', 100 / (i + 1), i)
writer.add_scalar('Accuracy/train', i / 100, i)
writer.close()
print(f"TensorBoard logs saved to: {log_dir}")
print("To view, run in your terminal: tensorboard --logdir runs")
tensorboard --version
Debug
Known issues
breakingTensorBoard.dev, the hosted sharing service, has been shut down. The `tensorboard dev upload` command will fail and the website is no longer accessible.fixMigrate to self-hosting TensorBoard or alternative experiment tracking platforms. There is no direct replacement for `tensorboard.dev` functionality within TensorBoard itself.
affects: >=2.15.1
gotchaTensorBoard plugin compatibility with Keras 3. While TensorFlow 2.16+ uses Keras 3 by default, some TensorBoard plugins' implementations may still primarily support Keras 2. This can lead to unexpected behavior or missing visualizations for Keras 3 models.fixMonitor official releases and documentation for Keras 3 compatibility updates. If issues arise, consider running Keras 2 compatible environments or alternative debugging strategies.
affects: >=2.16.0
gotchaProtobuf dependency conflicts can occur. TensorBoard's `protobuf` requirements have varied across versions (e.g., tight restrictions, then relaxations). This can cause installation errors or runtime issues if other installed libraries have conflicting `protobuf` version requirements.fixEnsure `protobuf` version is compatible with your TensorBoard installation. Use `pip check` to find conflicts and consider creating isolated virtual environments. If problems persist, try reinstalling `tensorboard` which often pulls a compatible `protobuf` version.
affects: All versions (historically problematic around 2.15.x - 2.18.x)
gotchaPython 3.13 compatibility requires TensorBoard version 2.20.0 or higher. Earlier versions will fail on Python 3.13 due to the removal of the `imghdr` module from the standard library, which TensorBoard previously used.fixUpgrade TensorBoard to version 2.20.0 or newer if using Python 3.13.
affects: <2.20.0 on Python 3.13
gotchaWhen using `SummaryWriter` in notebook environments (e.g., Colab, Jupyter), it's highly recommended to call `writer.flush()` and `writer.close()` after logging data. This ensures all event files are properly written to disk and available for TensorBoard to render, preventing data loss or incomplete visualizations.fixAlways explicitly call `writer.flush()` and `writer.close()` at the end of your logging session, or use `with SummaryWriter(...) as writer:` context manager.
affects: All versions
breakingWhen attempting to import `torch.utils.tensorboard.SummaryWriter`, a `ModuleNotFoundError: No module named 'torch'` indicates that the PyTorch library is not installed or not accessible in the environment. The `torch.utils.tensorboard` module is part of PyTorch and explicitly requires a PyTorch installation.fixInstall PyTorch. This can typically be done via pip: `pip install torch` or by following the specific installation instructions on the PyTorch website (e.g., `pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118` for CUDA-enabled versions).
affects: All versions (where `torch.utils.tensorboard` is used)
breakingThe `torch` library is a required dependency when using `torch.utils.tensorboard.SummaryWriter`. If `torch` is not installed, a `ModuleNotFoundError` will occur.fixEnsure `torch` is installed in your environment. For example, `pip install torch` (or specify a specific version/platform as per PyTorch installation instructions). If using `torch.utils.tensorboard`, `tensorboard` itself also needs to be installed via `pip install tensorboard`.
affects: All versions using `torch.utils.tensorboard`
Upgrade
Version history
2.21.0latest on PyPI · released Jun 29, 2026
Audit
Dependencies
PillowrequiredAdded as a dependency in 2.20.0 to replace the deprecated `imghdr` standard library module, ensuring compatibility with Python 3.13 and newer.
protobufrequiredTensorBoard has historically had specific requirements or restrictions on `protobuf` versions. While often relaxed, users should be aware of potential conflicts if other libraries pin `protobuf` to an incompatible version.
numpyrequiredCompatibility updates for `numpy` 2.0 were introduced in TensorBoard 2.18.0 and 2.17.1 to ensure proper functioning.
tf-kerasoptionalThe dependency on `tf-keras` (and `tf-keras-nightly` previously) was removed in TensorBoard 2.16.2. While not a direct dependency, Keras versions can impact plugin compatibility.
google-auth, google-auth-oauthlib, requestsoptionalThese libraries were removed as direct dependencies in TensorBoard 2.16.0. Users requiring their functionality in their own code should install them explicitly.