Skip to content

Installation

Requirements

  • Python 3.10 or newer.
  • uv (recommended) or pip.

Install

With pip

Install tensorboard-book from PyPI into a virtual environment:

python -m venv .venv
source .venv/bin/activate        # on Windows: .venv\Scripts\activate
pip install tensorboard-book

The tensorboard-book command is available while the environment is active. To upgrade to a newer version, run pip install --upgrade tensorboard-book.

To install the latest code from GitHub instead of the PyPI release:

pip install git+https://github.com/eagomez2/tensorboard-book

With uv

uv tool install puts the command in an environment of its own, so it is available everywhere without activating anything:

uv tool install tensorboard-book

From a copy of the repository

git clone https://github.com/eagomez2/tensorboard-book
cd tensorboard-book
pip install .            # or: uv tool install .

Check the installation

tensorboard-book --version

To work on the code instead, see CONTRIBUTING.md.

Start the app

Pass the folder that contains your runs, the same folder you would pass to tensorboard --logdir:

tensorboard-book /path/to/runs

The command first indexes the folder, then prints the address of the app:

  tensorboard-book 0.9.0

  Runs folder: /path/to/runs
  Database: /path/to/runs/.tensorboard-book/index.db
  Runs: 14 (14 new, 14 parsed)

  You can now view your Streamlit app in your browser.

  URL: http://127.0.0.1:8501
  • Browser. The app opens in a new browser tab. --no-browser turns this off. On a machine without a display, such as over SSH, no tab is opened.
  • Port. The app listens on port 8501, or on the next free port if 8501 is in use. With --port, that exact port is used, and the app stops if it is busy.
  • Address. The app listens on 127.0.0.1 by default, so only the same computer can reach it. Any other --host requires a password.

Set a password

Without a password hash, the app does not ask for a password. This is only allowed on 127.0.0.1. To require a password:

  1. Create a password hash. The password itself is never stored.

    tensorboard-book hash-password
# Password: ********
# Repeat:   ********
# TBOOK_PASSWORD_HASH=5c1f…:9ae2…

  2. Set it in the environment and start the app:

    export TBOOK_PASSWORD_HASH='5c1f…:9ae2…'
tensorboard-book /path/to/runs

When TBOOK_PASSWORD_HASH is set, the app asks for the password. --no-auth skips it for one launch, on 127.0.0.1 only. The app does not start if the hash is malformed, or if it is missing while --host is not local.

TBOOK_VIEWER_PASSWORD_HASH, created the same way, sets a second, read-only password. Viewers can browse and download, but not edit.

To reach the app from another computer, see Password and deployment.

Next steps