Install & Compatibility
Where this runs
tested against v0.4.3 · 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.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 226.3MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 11.3s · import 0.000s · 237MB
239MB installed
● package 239MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
tensorboard_trace_handler
✓ from torch_tb_profiler import tensorboard_trace_handler
✗ from torch_tb_profiler import tensorboard_trace_handler
To use `torch-tb-profiler`, first, you need to set up `torch.profiler` in your training loop to generate profiling data. Use `torch.profiler.tensorboard_trace_handler` as the `on_trace_ready` callback to save the trace files. After your script runs and generates the profiling data, launch TensorBoard from your terminal, pointing to the parent directory of your profiling logs. The plugin will automatically be available under the 'PYTORCH_PROFILER' tab in your TensorBoard UI.
import torch
import torch.nn as nn
import torch.optim as optim
from torch.profiler import profile, record_function, ProfilerActivity, tensorboard_trace_handler
import os
# Create a dummy model and data
model = nn.Linear(10, 10).cuda() if torch.cuda.is_available() else nn.Linear(10, 10)
optimizer = optim.SGD(model.parameters(), lr=0.01)
dummy_input = torch.randn(64, 10).cuda() if torch.cuda.is_available() else torch.randn(64, 10)
# Define log directory for TensorBoard
log_dir = "./runs/profiler_test"
# Run profiler
with profile(
schedule=torch.profiler.schedule(wait=1, warmup=1, active=3, repeat=2),
on_trace_ready=tensorboard_trace_handler(log_dir),
activities=[
ProfilerActivity.CPU,
ProfilerActivity.CUDA if torch.cuda.is_available() else ProfilerActivity.CPU,
],
record_shapes=True,
with_stack=True
) as prof:
for i in range(10):
optimizer.zero_grad()
output = model(dummy_input)
loss = output.sum()
loss.backward()
optimizer.step()
prof.step() # Advance profiler to next step
print(f"Profiling results saved to {log_dir}.\n")
print("To view in TensorBoard, run: ")
print(f"tensorboard --logdir {os.path.abspath(log_dir.split('/profiler_test')[0])}")
Debug
Known issues
breakingThe TensorBoard integration with PyTorch profiler (`tb_plugin` submodule, which this library provides) is deprecated and scheduled for permanent removal on March 5, 2026. Users are advised to consider migrating their workflow.fixMonitor PyTorch's official channels for alternative visualization tools or migration guides. Consider using Perfetto or Chrome trace viewer for raw `trace.json` files.
affects: All versions, specifically impacting usage after March 2026.
gotchaProfiling results may not be displayed in TensorBoard if the `torch.profiler` is not actively enabled and generating data in your code. Simply installing `torch-tb-profiler` is not enough to see results.fixEnsure your PyTorch code explicitly uses `torch.profiler.profile` with `tensorboard_trace_handler` to generate the necessary log files. Refer to the quickstart for an example.
affects: All versions
gotchaTrace files containing invalid values like 'inf' (e.g., in 'memory bandwidth (GB/s)') can cause `torch-tb-profiler` to fail when opening and visualizing the data in TensorBoard.fixThis often points to a bug in the PyTorch profiler's data generation. If encountered, report an issue to the PyTorch team with a minimal reproducible example. Workaround might involve manually cleaning invalid entries if feasible.
affects: All versions
gotchaWhen profiling CUDA activities, issues like mismatched CUDA toolkit versions between your environment and PyTorch installation, or improper use of `autocast` for mixed precision, can lead to incorrect or misleading GPU profiling results and performance.fixVerify that your PyTorch installation is compatible with your system's CUDA toolkit. Ensure `torch.profiler.ProfilerActivity.CUDA` is included in your profiler activities, and that your model operations are correctly moved to the GPU. For mixed precision, ensure `torch.cuda.amp.autocast()` is used where appropriate.
affects: All versions when using CUDA profiling
Upgrade
Version history
0.4.3latest on PyPI · released Oct 6, 2023
Audit
Dependencies
tensorboardrequiredThis package is a plugin for TensorBoard and requires TensorBoard to function.
torchrequiredThis plugin visualizes data generated by `torch.profiler`.
pandasoptionalUsed for data processing within the plugin.
azure-storage-bloboptionalOptional dependency for loading profiling data from Azure Blob Storage.
google-cloud-storageoptionalOptional dependency for loading profiling data from Google Cloud Storage.
boto3optionalOptional dependency for loading profiling data from AWS S3.