tensorboard_logger: writing TensorBoard events without importing TensorFlow

The point is to write the event files, not to run TensorFlow

The premise is narrow and worth stating precisely, because it is the whole reason the library exists.

TensorBoard is described in the project documentation as a visualization tool that makes it easy to check training progress and compare between different runs, and it is explicitly not this project, it is a part of the TensorFlow framework. That distinction is the design. The library writes the event files that TensorBoard reads, and does it without importing TensorFlow.

So the dependency story is: you install this package to write, and you install TensorFlow only for viewing. The documentation says TensorFlow is required only for viewing logged events, and points at the official installation guide, with the aside that you probably want a CPU-only version since the viewer does not need a GPU.

That is a real saving for a PyTorch project. TensorFlow is a large dependency to carry in a training environment purely so a summary writer can emit some scalars, and this library replaces it with protobuf plus a few numerical packages.

The author also points readers at the PyTorch documentation as an alternative that reaches the same goal and is part of PyTorch itself, and notes that if you are already using TensorFlow in your project you probably do not need this library at all. Both notes are fair, and the second one is the strongest argument against installing it in a TensorFlow codebase.

Two functions, one class, and a directory per run

The API is small enough to describe in a paragraph, which is a virtue in a logging library.

You can use the default logger with the configure and log_value functions, or use the Logger class. The class is for when the default logger is not enough, for example when you want to log into several different directories, or when you do not like global variables. Its constructor has the same signature as configure, and it has a single log_value method with the same signature as the module-level one.

configure(logdir, flush_secs=2) writes a file into logdir and is supposed to flush it every flush_secs. The API reference carries a note that right now the file is flushed after each event written, so the flush interval is not yet doing what the parameter name suggests. That is the kind of detail worth knowing before you point a high-frequency logger at it.

The directory convention is the other thing to understand. A log file is written into a directory, so you need a separate directory for each run, and you can place other logs or output files you use in the same directory. Directories from different runs you wish to compare should have the same parent, since TensorBoard works out which directories contain logs and you can have other files or directories with the same parent.

The unconfigure function simply resets the global default logger variable to None, which is the escape hatch if you need to switch loggers inside a long-running process.

In use, the pattern is a configure call followed by a loop that logs two values per step:

from tensorboard_logger import configure, log_value

configure("runs/run-1234", flush_secs=5)

for step in range(1000):
    v1, v2 = do_stuff()
    log_value('v1', v1, step)
    log_value('v2', v2, step)

That is the entire integration. Two imports, one configure, and a log call per scalar per step.

The step is the axis TensorBoard sorts on

The documentation puts more emphasis on the step than on the value, and it is right to.

Apart from variable names and their values, another important thing is the step, and it must be an integer representing some increasing step. It can be a step in training or some other number. The values are ordered by step in TensorBoard, although you can view them ordered by time or relative step too.

The rules for the value are looser. The value should be a real number and it will be converted to float, and the name should be a string and it will be converted to a valid TensorFlow summary name. The step should be a non-negative integer, and you can log several different variables on one step, but you should not log different values of the same variable on the same step, and that mistake is not checked.

That last clause is worth dwelling on. Nothing in the library will stop you from writing two different values for the same variable at the same step, and the result in the viewer is a corrupted series rather than an error. A logging library that silently accepts inconsistent writes is a good thing to know about before you trust a chart.

You can also omit the step entirely, which is documented as allowed. The value of doing so is questionable for anything you intend to compare across runs, since the ordering then falls back to time.

Once the files exist, viewing them is a TensorBoard command and a browser:

tensorboard --logdir runs

The metrics then appear in the TensorBoard UI at http://localhost:6006, with the note that it binds to 0.0.0.0 by default. That default binding is worth remembering on a shared machine, since it exposes the viewer on every interface rather than only on loopback.

The overhead figure, and the dependency set it drags in

The performance note in the documentation is unusually specific, and it is the number to plan around. The runtime overhead is described as rather large, about 0.1 to 0.2 ms for a single value logged, which works out at about 5,000 to 10,000 operations per second.

Put that in a training loop and it becomes concrete. A model logging ten scalars per step at 0.15 ms each is spending 1.5 ms per step on logging, on top of whatever the step costs. For a step that takes a second that is noise, and for a step that takes a millisecond it is the dominant cost. Since the flush happens after each event written rather than on the flush_secs interval, that cost is not amortised either.

The dependency list is worth looking at too, because it is the price of avoiding TensorFlow. The package requires protobuf, six, numpy, scipy >= 0.19.1 and pillow >= 4.1.1. The scipy and pillow requirements are there for the image and histogram summary types, and protobuf is doing the real work of serialising the event protocol.

So the trade is: you avoid TensorFlow and pick up protobuf, six, numpy, scipy and pillow instead. In a PyTorch environment numpy and scipy are almost certainly already present, and six is a Python 2 compatibility shim that this package still declares. The result is that the dependency saving is real but not as large as the framing suggests, and in a scientific Python environment it may be smaller than the cost of the library itself.

The package metadata records version 0.1.0.dev, author Konstantin Lopuhin, a Development Status of 2 - Pre-Alpha, and classifiers for Python 2, 2.7, 3, 3.4 and 3.5. The MIT licence is stated in the setup.py and in the LICENSE file.

Vendored protobufs, and how to regenerate them

The part of the repository that explains the design is the protobuf layer.

The library writes TensorBoard events, and the event and summary formats are defined in protobuf. Rather than depending on a TensorFlow install to get the generated Python bindings for those protos, the repository carries the definitions and the generated code, and the development section documents how to regenerate them with protoc:

protoc --python_out . tensorboard_logger/tf_protobuf/summary.proto
protoc --python_out . tensorboard_logger/tf_protobuf/event.proto

That is the whole reason the library works without TensorFlow, and it is also where the maintenance risk sits. The event format is TensorFlow's, so if TensorFlow changes the format, this vendored copy has to be regenerated to match. The repository history shows that has happened, since the root directory contains a bfg-1.15.0.jar, the tool used to strip large files from a git history, which is what you reach for after committing generated binaries by mistake.

The rest of the tree is a conventional Python packaging layout. There is setup.py with a long_description assembled from README.rst plus HISTORY.rst, setup.cfg, a MANIFEST.in, a requirements_dev.txt, a tox.ini for test environments, a .travis.yml for the old continuous integration service, a .coveragerc for coverage, and an AGENTS.md at the root alongside rules.json, which is the configuration for an agent-oriented workflow in the repository.

The package itself, the tests/ directory and the HISTORY.rst changelog complete the picture. There is no GitHub release for the project, and the last push to the repository was on 2026-04-08.

Where tensorboard_logger is the wrong tool

The first limit is the one the project states itself: if you are already using TensorFlow, you probably do not need this library. The TensorFlow summary writer is already installed, and its API is nearly identical. Installing this instead adds a second way to write the same files to a codebase, which is the kind of duplication that produces confusion later.

The second is that PyTorch has its own answer. The documentation points at the PyTorch TensorBoard documentation as reaching the same goal, and it is part of PyTorch, so in a PyTorch project the alternative is a built-in writer with the same output format. The difference in approach is that the PyTorch writer comes with the framework and is maintained alongside it, while this library maintains a vendored copy of the protobuf definitions and has to chase format changes by hand.

The third is the write cost, and it is not small. About 0.1 to 0.2 ms per value is not a rounding error for a fast training loop, and the file is flushed after every event written rather than on the configured interval, so the flush interval does not reduce it. A project logging many scalars at high frequency will feel this, and the fix is to log less often, which changes what the chart shows.

The fourth is what the library does not cover. The documented API is scalars: log_value for numerical values, with the name converted to a valid TensorFlow summary name. There is no documented interface for histograms, images, audio, text or anything else, even though the dependency on pillow and scipy suggests the underlying format supports them. If you need more than scalars, the API surface you are given is narrow and you will be writing protobuf calls yourself.

The fifth is the maintenance state. The version in the package metadata is 0.1.0.dev, the development status is Pre-Alpha, the classifiers stop at Python 3.5, and the last push was on 2026-04-08. The repository is not archived, but the combination of a pre-alpha version marker, an old interpreter range and a release line with no GitHub releases means you are depending on a package whose modern-Python compatibility is not something the metadata promises. That is checkable, and it should be checked before a training run depends on it.

Editorial conclusion

tensorboard_logger is worth installing for a PyTorch or NumPy project that wants TensorBoard's viewer without the TensorFlow dependency, because the whole surface is two functions and a class, because the event files are the standard format, and because the protobuf definitions are vendored so you do not need a matching TensorFlow install to write them. It is the wrong choice if you are already using TensorFlow, and the project says so. Before you adopt it, check the three things the documentation is honest about: that the overhead is around 0.1 to 0.2 ms per logged value, which is 5,000 to 10,000 operations per second, so a logging call per training step per metric adds up; that right now the file is flushed after each event written, regardless of the flush_secs setting, which is the surprise in the API reference; and that the version in the package metadata is 0.1.0.dev with a Development Status of 2 - Pre-Alpha and classifiers for Python 2.7 through 3.5, so check that it still installs on your interpreter.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. TeamHG-Memex/tensorboard_logger on GitHub