{"id":2305,"library":"tensorboardx","title":"TensorBoardX","description":"TensorBoardX is a Python library that enables logging events for TensorBoard visualizations without requiring TensorFlow as a dependency, making it compatible with frameworks like PyTorch, Chainer, MXNet, and NumPy. It supports logging various data types including scalars, images, audio, histograms, text, graphs, and embeddings to help researchers visualize and track machine learning experiment progress. The current version is 2.6.5, released on April 3, 2026, with active development and maintenance.","status":"active","version":"2.6.5","language":"en","source_language":"en","source_url":"https://github.com/lanpa/tensorboardX.git","tags":["machine learning","logging","visualization","pytorch","deep learning","numpy","chainer","mxnet"],"install":[{"cmd":"pip install tensorboardx","lang":"bash","label":"Basic installation"},{"cmd":"pip install tensorboardx crc32c soundfile tensorboard","lang":"bash","label":"With optional speedups and TensorBoard for viewing"}],"dependencies":[{"reason":"Core dependency for data handling.","package":"numpy","optional":false},{"reason":"Used for version parsing and compatibility.","package":"packaging","optional":false},{"reason":"Required for serializing data into TensorBoard's event file format. Version >=5.29.6 is required for 2.6.5.","package":"protobuf","optional":false},{"reason":"Optional, provides speedup for CRC32C checksum calculations.","package":"crc32c","optional":true},{"reason":"Optional, significantly speeds up the `add_audio()` function (200x speedup from v2.1).","package":"soundfile","optional":true},{"reason":"Required to run the TensorBoard web server to view the logs generated by TensorBoardX.","package":"tensorboard","optional":true}],"imports":[{"note":"This is the primary class for writing events to TensorBoard logs.","symbol":"SummaryWriter","correct":"from tensorboardX import SummaryWriter"}],"quickstart":{"code":"import torch\nimport numpy as np\nfrom tensorboardX import SummaryWriter\n\n# Create a writer instance, logs will be saved in 'runs/my_experiment'\nwriter = SummaryWriter('runs/my_experiment')\n\n# Log scalar values\nfor i in range(100):\n    writer.add_scalar('training/loss', 100 - i * 0.5 + np.random.rand(), i)\n    writer.add_scalar('training/accuracy', 0.5 + i * 0.005 + np.random.rand() * 0.01, i)\n\n# Log a Pytorch model graph (dummy model and input)\ntry:\n    import torch.nn as nn\n    class SimpleModel(nn.Module):\n        def __init__(self):\n            super().__init__()\n            self.linear = nn.Linear(10, 2)\n        def forward(self, x):\n            return self.linear(x)\n    dummy_input = torch.randn(1, 10)\n    model = SimpleModel()\n    writer.add_graph(model, dummy_input)\nexcept ImportError:\n    print(\"PyTorch not installed, skipping add_graph example.\")\n\n# Close the writer to flush all pending events to disk\nwriter.close()\n\nprint(\"TensorBoardX logs written to 'runs/my_experiment'.\")\nprint(\"To view these logs, run the following command in your terminal:\")\nprint(\"  tensorboard --logdir=runs\")","lang":"python","description":"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."},"warnings":[{"fix":"Check 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`).","message":"The `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.","severity":"breaking","affected_versions":"<2.6.5"},{"fix":"Install `tensorboard` alongside `tensorboardx`: `pip install tensorboardx tensorboard`. Then run the server with `tensorboard --logdir=<your_log_dir>`.","message":"TensorBoardX 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Consider 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.","message":"Logging 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Instead of `writer.add_scalar('tag', torch_tensor, iteration)`, use `writer.add_scalar('tag', torch_tensor.item(), iteration)`.","message":"When logging PyTorch scalar tensors, you must extract the Python scalar value using `.item()` before passing it to `add_scalar()`, otherwise `tensorboardX` may complain.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For optimal performance with `add_audio()`, ensure `tensorboardX` is v2.1 or newer and install `soundfile`: `pip install soundfile`.","message":"The `add_audio()` function was significantly optimized (200x speedup) starting from version 2.1, but this requires the `soundfile` package to be installed.","severity":"deprecated","affected_versions":"<2.1"},{"fix":"If 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.","message":"From `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.","severity":"breaking","affected_versions":"<2.1"},{"fix":"Avoid 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.","message":"Importing `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.","severity":"gotcha","affected_versions":"All versions (observed in 1.8 and later)"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}