{"id":6267,"library":"torch-tb-profiler","title":"PyTorch Profiler TensorBoard Plugin","description":"torch-tb-profiler is a TensorBoard plugin that provides rich visualizations and analysis tools for profiling PyTorch models. It parses, processes, and visualizes profiling results dumped by `torch.profiler`, helping users identify performance bottlenecks and receive optimization recommendations. The current version is 0.4.3, with releases often tied to PyTorch updates or major bug fixes.","status":"active","version":"0.4.3","language":"en","source_language":"en","source_url":"https://github.com/pytorch/kineto/tree/main/tb_plugin","tags":["pytorch","tensorboard","profiling","performance","deep-learning","gpu"],"install":[{"cmd":"pip install torch-tb-profiler","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"This package is a plugin for TensorBoard and requires TensorBoard to function.","package":"tensorboard"},{"reason":"This plugin visualizes data generated by `torch.profiler`.","package":"torch"},{"reason":"Used for data processing within the plugin.","package":"pandas","optional":true},{"reason":"Optional dependency for loading profiling data from Azure Blob Storage.","package":"azure-storage-blob","optional":true},{"reason":"Optional dependency for loading profiling data from Google Cloud Storage.","package":"google-cloud-storage","optional":true},{"reason":"Optional dependency for loading profiling data from AWS S3.","package":"boto3","optional":true}],"imports":[{"note":"This handler is passed to `torch.profiler.profile` to generate trace files compatible with the torch-tb-profiler plugin. The plugin itself is not directly imported into user code.","symbol":"tensorboard_trace_handler","correct":"from torch.profiler import tensorboard_trace_handler"}],"quickstart":{"code":"import torch\nimport torch.nn as nn\nimport torch.optim as optim\nfrom torch.profiler import profile, record_function, ProfilerActivity, tensorboard_trace_handler\nimport os\n\n# Create a dummy model and data\nmodel = nn.Linear(10, 10).cuda() if torch.cuda.is_available() else nn.Linear(10, 10)\noptimizer = optim.SGD(model.parameters(), lr=0.01)\ndummy_input = torch.randn(64, 10).cuda() if torch.cuda.is_available() else torch.randn(64, 10)\n\n# Define log directory for TensorBoard\nlog_dir = \"./runs/profiler_test\"\n\n# Run profiler\nwith profile(\n    schedule=torch.profiler.schedule(wait=1, warmup=1, active=3, repeat=2),\n    on_trace_ready=tensorboard_trace_handler(log_dir),\n    activities=[\n        ProfilerActivity.CPU,\n        ProfilerActivity.CUDA if torch.cuda.is_available() else ProfilerActivity.CPU,\n    ],\n    record_shapes=True,\n    with_stack=True\n) as prof:\n    for i in range(10):\n        optimizer.zero_grad()\n        output = model(dummy_input)\n        loss = output.sum()\n        loss.backward()\n        optimizer.step()\n        prof.step() # Advance profiler to next step\n\nprint(f\"Profiling results saved to {log_dir}.\\n\")\nprint(\"To view in TensorBoard, run: \")\nprint(f\"tensorboard --logdir {os.path.abspath(log_dir.split('/profiler_test')[0])}\")","lang":"python","description":"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."},"warnings":[{"fix":"Monitor PyTorch's official channels for alternative visualization tools or migration guides. Consider using Perfetto or Chrome trace viewer for raw `trace.json` files.","message":"The 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.","severity":"breaking","affected_versions":"All versions, specifically impacting usage after March 2026."},{"fix":"Ensure 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.","message":"Profiling 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"This 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.","message":"Trace 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Verify 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.","message":"When 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.","severity":"gotcha","affected_versions":"All versions when using CUDA profiling"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}