TabPFN Environment Variables: How to Configure TABPFN_TOKEN and TABPFN_MODEL_CACHE_DIR

TabPFN uses TABPFN_TOKEN for API authentication and TABPFN_MODEL_CACHE_DIR for custom model storage locations, allowing headless deployment and cache management without modifying code.

TabPFN (PriorLabs/TabPFN) reads runtime configuration from environment variables prefixed with TABPFN_. The two most critical variables—TABPFN_TOKEN and TABPFN_MODEL_CACHE_DIR—control licensing and model persistence. Understanding these settings enables seamless integration in CI/CD pipelines and custom deployment environments.

Setting the API Token with TABPFN_TOKEN

The TABPFN_TOKEN environment variable supplies the license token required for authentication. When this variable is unset, TabPFN launches an interactive browser flow to obtain credentials, which blocks automated workflows.

In src/tabpfn/browser_auth.py, the authentication routine checks for this token before initiating browser-based authentication. If the token is missing and the environment is headless, the library raises an error to prevent hanging processes.

When to use it:

• Required for CI/CD pipelines, Docker containers, and server environments without displays
• Required for automated testing suites that import TabPFN
• Optional for local development (falls back to browser login)

export TABPFN_TOKEN="your-api-key-here"

Customizing Model Cache with TABPFN_MODEL_CACHE_DIR

The TABPFN_MODEL_CACHE_DIR variable overrides the default directory where TabPFN downloads and stores model files. By default, the library uses a platform-specific user cache directory (typically ~/.cache/tabpfn on Linux).

In src/tabpfn/settings.py, the TabPFNSettings class maps this environment variable to the model_cache_dir attribute. Both TabPFNClassifier (in src/tabpfn/classifier.py) and TabPFNRegressor (in src/tabpfn/regressor.py) reference this setting when initializing models.

Usage pattern:

• Specify absolute paths for persistent storage across container restarts
• Use network-mounted directories for shared cache environments
• Redirect to ephemeral storage in serverless deployments

export TABPFN_MODEL_CACHE_DIR="/data/tabpfn_models"

Implementation Examples

Shell Configuration

Set both variables before launching Python:

export TABPFN_TOKEN="sk-xxxxxxxxxxxxxxxx"
export TABPFN_MODEL_CACHE_DIR="/mnt/faststorage/tabpfn_cache"
python train_model.py

Python Runtime Configuration

Environment variables are read at import time or class instantiation:

import os

# Must set before importing or before first model instantiation

os.environ["TABPFN_TOKEN"] = "my-secret-token"
os.environ["TABPFN_MODEL_CACHE_DIR"] = "/tmp/tabpfn_models"

from tabpfn import TabPFNRegressor

# Model downloads (or loads from) the custom cache directory

model = TabPFNRegressor()
model.fit(X_train, y_train)

CI/CD Pipeline (GitHub Actions)

For headless testing environments, inject secrets as environment variables:

jobs:
  train:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install tabpfn
      - name: Run training with authenticated TabPFN
        env:
          TABPFN_TOKEN: ${{ secrets.TABPFN_TOKEN }}
          TABPFN_MODEL_CACHE_DIR: ${{ runner.temp }}/tabpfn_models
        run: python -c "from tabpfn import TabPFNClassifier; TabPFNClassifier()"

Source Code Implementation Details

Configuration Model in settings.py

The TabPFNSettings class in src/tabpfn/settings.py defines the schema for environment variable mapping. This Pydantic-based settings model validates TABPFN_MODEL_CACHE_DIR and converts relative paths to absolute paths before storage.

Authentication Handling in browser_auth.py

The src/tabpfn/browser_auth.py module implements the token resolution logic. It first checks for TABPFN_TOKEN in the environment; if absent, it launches a local HTTP server to handle the OAuth callback from the browser authentication flow.

Model Loading Integration

Both src/tabpfn/classifier.py and src/tabpfn/regressor.py consume these settings during initialization. They pass the model_cache_dir value to the underlying model loader, ensuring downloaded weights persist to the specified location.

Additional Environment Variables

While TABPFN_TOKEN and TABPFN_MODEL_CACHE_DIR handle licensing and storage, other variables exist for specialized configurations:

• TABPFN_DISABLE_TELEMETRY: Opts out of usage analytics
• TABPFN_MPS_MEMORY_FRACTION: Controls memory allocation for Metal Performance Shaders on macOS

These variables follow the same TABPFN_ prefix convention but do not affect authentication or caching behavior.

Summary

• TABPFN_TOKEN provides the API license key required for non-interactive authentication, as processed in src/tabpfn/browser_auth.py
• TABPFN_MODEL_CACHE_DIR overrides the default cache location for model files, configured in src/tabpfn/settings.py
• Both variables use the TABPFN_ prefix and are read automatically during class initialization
• Setting these variables is mandatory for CI/CD environments, Docker containers, and any headless deployment scenario

Frequently Asked Questions

What happens if I don't set TABPFN_TOKEN?

If TABPFN_TOKEN is unset and you are running in an interactive environment with a display, TabPFN opens a browser window for OAuth authentication. In headless environments without a display, the library raises a RuntimeError indicating that the token is required for authentication.

Can I use a relative path for TABPFN_MODEL_CACHE_DIR?

While the settings model in src/tabpfn/settings.py accepts relative paths, it resolves them to absolute paths using Path.resolve(). For production deployments, absolute paths are recommended to avoid ambiguity about the working directory.

Are TabPFN environment variables case-sensitive?

Yes, environment variable names are case-sensitive. You must use uppercase TABPFN_TOKEN and TABPFN_MODEL_CACHE_DIR. The library uses exact string matching when reading from os.environ, and lowercase variants will not be recognized.

How do I set TabPFN environment variables in a Docker container?

Pass them using the -e flag or an env file. For persistent caching, mount a volume to the cache directory:

docker run -e TABPFN_TOKEN=$TOKEN \
           -e TABPFN_MODEL_CACHE_DIR=/app/cache \
           -v $(pwd)/tabpfn_cache:/app/cache \
           my-tabpfn-image

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}