tensorboardX: Writing TensorBoard Event Files Without TensorFlow

The gap tensorboardX fills: event files without a TensorFlow install

TensorBoard reads a directory of event files. Historically the writer that produced those files shipped inside TensorFlow, which meant a PyTorch user who wanted the scalar, histogram and image panes had to install a framework they were not training with. tensorboardX inverts that: it is a standalone Python package that writes the same event format from ordinary function calls. The README states the purpose in one line, "Write TensorBoard events with simple function call." The reader is a PyTorch, Chainer, MXNet or NumPy user who wants the TensorBoard UI but not the TensorFlow dependency. The library is MIT-licensed, so it can be vendored or embedded in a closed training pipeline without a licensing conversation, though that is a statement about the licence text and not legal advice.

SummaryWriter, add_* calls, and where the data actually lands

The mechanism is a single writer object plus one method per summary type. The README example constructs `writer = SummaryWriter()`, then calls `writer.add_scalar('data/scalar1', dummy_s1[0], n_iter)`, `writer.add_scalars('data/scalar_group', {...}, n_iter)`, `writer.add_image`, `writer.add_audio`, `writer.add_text`, `writer.add_histogram`, `writer.add_pr_curve` and `writer.add_embedding`. Each call takes a tag, the payload, and a global step. Tags are hierarchical: the README notes "data grouping by `slash`", so `data/scalar1` and `data/scalar2` collapse under a `data` group in the sidebar. Nothing is rendered by tensorboardX itself. The writer serialises the payload into event files under a log directory, and a separate `tensorboard` process reads that directory. That split is the whole architecture, and it explains both the library's small surface area and its main operational constraint: the log directory is the interface between your training process and the UI. Supported summary types listed in the README are scalar, image, figure, histogram, audio, text, graph, onnx_graph, embedding, pr_curve, mesh, hyper-parameters and video. The writer also exposes `writer.export_scalars_to_json("./all_scalars.json")`, which dumps scalar data for processing outside TensorBoard, and `writer.close()`, which the example calls at the end. Omitting that close is a plausible way to lose buffered events, since the example treats it as part of the normal lifecycle.

Install, optional accelerators, and the soundfile requirement

Installation is one command: `pip install tensorboardX`. A source build is documented as `pip install 'git+https://github.com/lanpa/tensorboardX'`. Two optional packages change behaviour. The README says you can install `crc32c` to speed up, via `pip install crc32c`, which suggests the event-writing path computes CRC32C checksums and can use a C implementation when present. More consequential is audio: "Starting from tensorboardX 2.1, You need to install `soundfile` for the `add_audio()` function (200x speedup)." Read that carefully. It is not merely a performance note. If your code calls `add_audio()` and `soundfile` is absent, the README's wording implies the function is not usable as before. Anyone upgrading a pre-2.1 codebase should treat `pip install soundfile` as a migration step rather than an optimisation. The demo workflow is explicit: clone the files in the `examples` directory, run `python examples/demo.py`, then start the UI with `tensorboard --logdir runs`. Note that the log directory in that command, `runs`, is the default the example produces, so a different `SummaryWriter(logdir=...)` value means a different `--logdir` argument. The README also points to a FAQ wiki and to a tweak for showing more image history in the slider, referencing a GitHub issue and a TensorFlow TensorBoard pull request, which is a reminder that some UI behaviour lives upstream in TensorBoard and not in this package.

Version drift is the real maintenance cost

The release history in the supplied material is uneven. v2.5 landed in June 2022. v2.6.4 arrived in September 2025. v2.6.5 followed in April 2026. So there was a multi-year gap in tagged releases, then two releases inside roughly seven months. The README states that the current release, v2.6.5, is tested with PyTorch 2.6, torchvision 0.21.0 and tensorboard 2.19.0 on Python 3.10 to 3.13. That is a narrow tested matrix stated in the project's own words, and it is the number to check against your environment. Two costs follow. First, TensorBoard itself moves independently of tensorboardX. The writer emits event files; the reader is a separate install whose version you control. A summary type that the writer emits correctly can still render badly, or not at all, under a much older or much newer TensorBoard. Second, the optional dependencies are not pinned by the core install. `crc32c` and `soundfile` are separate `pip install` lines, so a container image built from `pip install tensorboardX` alone will silently lack the audio path. For a library whose entire job is producing a file format consumed by another project, that coupling is the main thing to track in CI: pin the tensorboard version alongside tensorboardX and re-run your logging smoke test when either moves.

Where tensorboardX is the wrong tool

tensorboardX writes files. It does not host runs, compare experiments across machines, version datasets, or diff two training configurations. If your team needs a shared experiment tracker with a queryable run history, this package does not attempt that, and adding more `add_scalar` calls will not get you there. The README does document an integration path: it states that tensorboardX now supports logging directly to Comet, described in the README as a free cloud-based solution that adds dataset management and experiment diffing on top of TensorBoard, and that this "works out of the box and just require an additional line of code", with a Colab notebook linked as a full example. Treat that as an integration offered by the README, not as a feature of the library. The other wrong-tool case is simpler: if you are already training in TensorFlow, `tf.summary` writes the same event files natively, and adding tensorboardX to that environment buys you a second writer for a format you already produce. There is also a scope boundary worth naming. The README's tagline mentions PyTorch, Chainer, MXNet and NumPy, but the tested matrix covers PyTorch, torchvision and tensorboard only. Frameworks outside that matrix are supported in the sense that the writer accepts arrays and scalars, not in the sense that the project states it tests them.

The alternative: tf.summary, and what actually differs

The closest alternative is TensorFlow's own `tf.summary` module with a `tf.summary.create_file_writer`. Both write event files that TensorBoard reads, and both are driven by the same `tensorboard --logdir` command. The difference is dependency direction. `tf.summary` requires TensorFlow to be installed and imported, which for a PyTorch project means a large second framework in the image and a second set of CUDA and Python version constraints to reconcile. tensorboardX requires only the tensorboard package to view the output, and the README's install section is a single `pip install tensorboardX` plus optional `crc32c` and `soundfile`. The API shape differs too: `tf.summary` is built around a context manager and a step argument, while tensorboardX is a stateful `SummaryWriter` object with one method per summary type and an explicit `close()`. Neither difference is decisive on its own. The dependency question is the one that usually decides it, and it decides in tensorboardX's favour only when TensorFlow is genuinely absent from the environment. If TensorFlow is already there for other reasons, the argument for adding a second writer largely disappears.

Who should adopt it, and what to check before you do

Adopt tensorboardX when the training code is PyTorch, Chainer, MXNet or NumPy, when TensorFlow is not otherwise in the environment, and when the TensorBoard UI is sufficient for how the team inspects runs. Do not adopt it when TensorFlow is already present, or when the requirement is a shared tracker with dataset management and cross-run diffing, since the library's own answer to that is the Comet integration rather than anything built in. The first thing to verify is version alignment: the README pins v2.6.5 to tensorboard 2.19.0 and PyTorch 2.6 on Python 3.10 to 3.13, so confirm your installed tensorboard renders each summary type you intend to use, particularly the less common ones such as `mesh`, `onnx_graph` and `hyper-parameters`. The second is the audio path: run `pip install soundfile` if `add_audio()` appears anywhere in your logging code, because the README treats it as required from 2.1 onward. The third is the writer lifecycle in your own training script. The README example ends with `writer.close()` and also demonstrates `writer.export_scalars_to_json("./all_scalars.json")` for pulling scalar data out of the event files. If your loop exits on an exception without reaching `close()`, you are relying on behaviour the README does not describe, so a `try`/`finally` around the writer is the one structural change worth making before you trust the logs from a multi-hour run.

Editorial conclusion

Adopt tensorboardX if your training loop is PyTorch, Chainer, MXNet or plain NumPy and you want TensorBoard's UI without pulling TensorFlow into the environment. Skip it if your stack is already TensorFlow-based (tf.summary is the native path) or if you need hosted experiment tracking with dataset versioning and run diffing, which this package does not provide. Before committing, verify two things on your own machine: that the installed tensorboard version renders every summary type you plan to log, since the README pins its test matrix to tensorboard 2.19.0, and that soundfile is installed if add_audio() is in your logging path, because the README states the audio path changed in 2.1 and that soundfile is now required.

Official sources

1. lanpa/tensorboardX on GitHub
2. License: MIT
3. Project website
4. README
5. Releases