Environment Variables

Trackio uses environment variables to configure various aspects of its behavior, particularly for deployment to Hugging Face Spaces and dataset persistence. This guide covers the main environment variables and their usage.

Core Environment Variables

TRACKIO_DIR

Specifies a custom directory for storing Trackio data. By default, Trackio stores data in ~/.cache/huggingface/trackio/.

export TRACKIO_DIR="/path/to/trackio/data"

Note: This environment variable applies as long as Trackio is not running in a Space with persistent storage enabled. If Trackio is running in a Space with persistent storage enabled (which is detected with the PERSISTANT_STORAGE_ENABLED env variable), then the Trackio data will be stored in /data/trackio.

TRACKIO_SERVER_URL

Base URL of a self-hosted Trackio server (http:// or https://). You may include write_token in the query string (as in the full_url from trackio.show()), or keep the URL bare and set TRACKIO_WRITE_TOKEN instead. When set, trackio.init() sends metrics to that server. Equivalent to passing server_url= to trackio.init().

Precedence: If TRACKIO_SPACE_ID is also set (or space_id is passed in code), the Hugging Face Space is used and TRACKIO_SERVER_URL is ignored. Same rule when both space_id and server_url are passed: space_id wins.

See Self-host the Server.

export TRACKIO_SERVER_URL="http://127.0.0.1:7860"
export TRACKIO_WRITE_TOKEN="YOUR_TOKEN"

TRACKIO_WRITE_TOKEN

The dashboard write token for a self-hosted Trackio server (same value as the write_token query parameter in the write-access URL). Use this when TRACKIO_SERVER_URL or server_url is a base URL without query parameters. The client sends this token on each request (for example as the X-Trackio-Write-Token header) so metric ingestion and uploads are authenticated when not running on Hugging Face Spaces.

TRACKIO_FRONTEND_DIR

Path to a custom static frontend directory for Trackio. The directory must contain index.html.

When set, Trackio uses that frontend for trackio.show() and for deploy flows such as trackio.sync() and trackio.freeze(), unless an explicit frontend_dir / --frontend argument is passed.

export TRACKIO_FRONTEND_DIR="/path/to/my-trackio-frontend"

If the configured directory is invalid, Trackio ignores it and falls back to the built-in frontend selection logic. The automatic starter-template copy behavior only applies when an explicit frontend_dir / --frontend argument points to a missing or empty directory.

TRACKIO_LOGO_LIGHT_URL and TRACKIO_LOGO_DARK_URL

Customize the logos displayed in the Trackio dashboard for light and dark themes. You can provide URLs to custom logos. Note that both environment variables should be supplied; otherwise, the Trackio default will be used for any variable that is not provided.

export TRACKIO_LOGO_LIGHT_URL="https://example.com/logo-light.png"
export TRACKIO_LOGO_DARK_URL="https://example.com/logo-dark.png"

Note: For remote Trackio Spaces, these environment variables are only applied when the Space is first created via trackio.init(space_id=...). To change logos on an existing Space, update the Space variables directly in the Hugging Face Space settings.

TRACKIO_PLOT_ORDER

Controls the ordering of plots and metric groups in the Trackio dashboard. The value should be a comma-separated list of metric patterns that specify the desired order. Groups are preserved - if train/loss is specified first, all other train/* metrics will appear together in the train group, with train/loss appearing first within that group.

If a pattern doesn’t match any metrics, it’s simply ignored without causing errors.

export TRACKIO_PLOT_ORDER="train/loss,val/loss"


**Pattern Matching:**
- **Exact matches**: `train/loss` matches exactly `train/loss`
- **Group wildcards**: `train/*` matches all metrics starting with `train/`
- **Partial wildcards**: `*gpu*` matches any metric containing "gpu"

**Behavior:**
- Metrics are grouped first (e.g., all `train/*` metrics stay together)
- Within each group, metrics are ordered according to the specified patterns
- Groups appear in the order of their first matching pattern
- Unspecified metrics appear in alphabetical order after specified ones

> **Note:** For remote Trackio Spaces, this environment variable is only applied when the Space is first created via `trackio.init(space_id=...)`. To change the plot order on an existing Space, update the `TRACKIO_PLOT_ORDER` Space variable directly in the Hugging Face Space settings.

### `TRACKIO_THEME`

Sets the theme for the Trackio dashboard. Can be a built-in Gradio theme name or a theme from the Hugging Face Hub.

```bash
# Built-in themes
export TRACKIO_THEME="soft"
export TRACKIO_THEME="citrus"
export TRACKIO_THEME="monochrome"

# Themes from the Hub
export TRACKIO_THEME="gstaff/xkcd"
export TRACKIO_THEME="ParityError/Anime"

Note: For remote Trackio Spaces, this environment variable is only applied when the Space is first created via trackio.init(space_id=...). To change the theme on an existing Space, update the TRACKIO_THEME Space variable directly in the Hugging Face Space settings.

TRACKIO_COLOR_PALETTE

Customizes the color palette used for plot lines in the Trackio dashboard. The value should be a comma-separated list of hex color codes. These colors will be cycled through when plotting multiple runs.

export TRACKIO_COLOR_PALETTE="#FF0000,#00FF00,#0000FF,#FFFF00,#FF00FF,#00FFFF"

Default palette: #A8769B, #E89957, #3B82F6, #10B981, #EF4444, #8B5CF6, #14B8A6, #F59E0B, #EC4899, #06B6D4

TRACKIO_TABLE_TRUNCATE_LENGTH

Controls the maximum length of string values displayed in table cells before they are truncated. When a cell value exceeds this length, it will be truncated with an expandable element that allows viewing the full text. Defaults to 250 characters.

export TRACKIO_TABLE_TRUNCATE_LENGTH="500"

TRACKIO_WEBHOOK_URL

Sets a global webhook URL for alerts. When set, every call to trackio.alert() will POST the alert payload to this URL. Supports Slack and Discord webhook URLs natively (payloads are formatted automatically). Can be overridden per-alert or per-run via the webhook_url parameter.

export TRACKIO_WEBHOOK_URL="https://hooks.slack.com/services/T.../B.../xxx"

See the Alerts guide for more details.

TRACKIO_WEBHOOK_MIN_LEVEL

Sets the minimum alert level that should be sent to webhooks. Alerts below this level are still printed to terminal, stored in the database, and shown in the dashboard, but are not sent to webhook destinations.

Allowed values: info, warn, error.

export TRACKIO_WEBHOOK_MIN_LEVEL="warn"

With warn, only WARN and ERROR alerts are sent to webhook URLs.

HF_TOKEN

Your Hugging Face authentication token. Required for creating Spaces and Buckets on Hugging Face. Set this locally when deploying to Spaces from your machine. Must have write permissions for the namespace that you are deploying the Trackio dashboard.

export HF_TOKEN="hf_xxxxxxxxxxxxx"

Gradio Environment Variables

Since Trackio is built on top of Gradio, you can use environment variables used by Gradio to control the behavior of Trackio. Here are a few examples:

GRADIO_SERVER_PORT

Specifies the port on which the Tradio dashboard will launch. Defaults to 7860

export GRADIO_SERVER_PORT=8000

GRADIO_SERVER_NAME

Defines the host name for the Trackio dashboard server. To make the dasbhoard accessible from any IP address, set this to "0.0.0.0"

export GRADIO_SERVER_NAME="0.0.0.0"

GRADIO_MCP_SERVER

Enables the MCP (Model Context Protocol) server functionality in Trackio. When enabled, the Trackio dashboard will be set up as an MCP server and certain functions will be exposed as MCP tools that can be used by LLMs (e.g. to read the logged metrics).

export GRADIO_MCP_SERVER="True"

See this more comprehensive list of environment variables used by Gradio.

Update on GitHub