# TabPFN Environment Variables: How to Configure TABPFN_TOKEN and TABPFN_MODEL_CACHE_DIR

> Configure TabPFN environment variables like TABPFN_TOKEN for API authentication and TABPFN_MODEL_CACHE_DIR for custom model storage, enabling headless deployment and cache control.

- Repository: [Prior Labs/TabPFN](https://github.com/PriorLabs/TabPFN)
- Tags: how-to-guide
- Published: 2026-05-06

---

**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`](https://github.com/PriorLabs/TabPFN/blob/main/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)

```bash
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`](https://github.com/PriorLabs/TabPFN/blob/main/src/tabpfn/settings.py), the `TabPFNSettings` class maps this environment variable to the `model_cache_dir` attribute. Both `TabPFNClassifier` (in [`src/tabpfn/classifier.py`](https://github.com/PriorLabs/TabPFN/blob/main/src/tabpfn/classifier.py)) and `TabPFNRegressor` (in [`src/tabpfn/regressor.py`](https://github.com/PriorLabs/TabPFN/blob/main/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

```bash
export TABPFN_MODEL_CACHE_DIR="/data/tabpfn_models"

```

## Implementation Examples

### Shell Configuration

Set both variables before launching Python:

```bash
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:

```python
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:

```yaml
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`](https://github.com/PriorLabs/TabPFN/blob/main/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`](https://github.com/PriorLabs/TabPFN/blob/main/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`](https://github.com/PriorLabs/TabPFN/blob/main/src/tabpfn/classifier.py)** and **[`src/tabpfn/regressor.py`](https://github.com/PriorLabs/TabPFN/blob/main/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`](https://github.com/PriorLabs/TabPFN/blob/main/src/tabpfn/browser_auth.py)
- **`TABPFN_MODEL_CACHE_DIR`** overrides the default cache location for model files, configured in [`src/tabpfn/settings.py`](https://github.com/PriorLabs/TabPFN/blob/main/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`](https://github.com/PriorLabs/TabPFN/blob/main/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:

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

```