User Data & Configuration Locations

This project follows the XDG Base Directory Specification for storing user data and configuration.

Directory Structure

Project Directory

The project directory contains read-only defaults and optional compatibility locations:

<project>/
├── config/
│   └── defaults.json       # Project defaults (in Git)
├── results/                # Optional: legacy/manual compatibility location
└── logs/                   # Optional: legacy/manual debug location

User Directories (XDG Standard)

User-specific data is stored in standard XDG locations:

~/.config/lm-studio-bench/
├── defaults.json           # User configuration overrides (optional)
└── presets/
    ├── my_fast_test.json   # User preset example
    └── my_quality.json     # User preset example

~/.local/share/lm-studio-bench/results/
├── benchmark_results_<timestamp>.json
├── benchmark_results_<timestamp>.csv
├── benchmark_results_<timestamp>.pdf
├── benchmark_results_<timestamp>.html
├── benchmark_cache.db      # SQLite benchmark cache
├── model_metadata.db       # Model metadata cache
└── metadata/
    └── <model_id>/
        └── metadata.json   # Optional per-model metadata fallback

~/.local/share/lm-studio-bench/logs/
├── benchmark_<timestamp>.log
├── benchmark_latest.log    # Symlink to newest benchmark log
├── webapp_<timestamp>.log
├── webapp_latest.log       # Symlink to newest webapp log
├── runapp_<timestamp>.log
├── runapp_latest.log       # Symlink to newest launcher log
├── trayapp_<timestamp>.log
└── trayapp_latest.log      # Symlink to newest tray log

Configuration Loading

Configuration is loaded with the following priority:

CLI Arguments (highest priority)
User Config (~/.config/lm-studio-bench/defaults.json)
Project Config (config/defaults.json)
Hard-coded Defaults (in code)

Example

Project (config/defaults.json):

{
  "num_runs": 3,
  "context_length": 2048,
  "lmstudio": {
    "use_rest_api": false
  }
}

User (~/.config/lm-studio-bench/defaults.json):

{
  "num_runs": 5,
  "lmstudio": {
    "use_rest_api": true
  }
}

Result (merged configuration):

{
  "num_runs": 5,              // User override
  "context_length": 2048,     // Project default
  "lmstudio": {
    "use_rest_api": true      // User override
  }
}

With CLI:

./run.py --runs 10 --context 4096

Final configuration:

num_runs: 10 (CLI)
context_length: 4096 (CLI)
use_rest_api: true (User config)

Creating User Configuration

Step 1: Create Config Directory

mkdir -p ~/.config/lm-studio-bench

Step 2: Create User Config File

nano ~/.config/lm-studio-bench/defaults.json

Step 3: Add Your Overrides

Only include fields you want to override:

{
  "num_runs": 5,
  "context_length": 4096,
  "inference": {
    "temperature": 0.7
  }
}

Important: You only need to specify fields you want to change. All other values will use project defaults.

Directory Initialization

On first run, the tool automatically:

Creates user data directories (~/.config/... and ~/.local/share/...)
Places new results in ~/.local/share/lm-studio-bench/results/
Places runtime logs in ~/.local/share/lm-studio-bench/logs/

Note: Legacy files in project-local results/ are not automatically moved. If you still use that location, move them manually to the XDG path.

Benefits of XDG Structure

For Users

✅ Persistent User Settings: Configuration survives project updates
✅ Cleaner Project Directory: User data separated from code
✅ Standard Locations: Follows Linux conventions
✅ Easy Backups: Backup ~/.local/share/lm-studio-bench/ and ~/.config/lm-studio-bench/
✅ Multi-User Support: Each user has their own data

For Developers

✅ No Git Conflicts: User data not in version control
✅ Clean Updates: git pull doesn't affect user data
✅ Portable: Project directory can be moved/deleted without losing user data

Environment Variables

You can override paths with environment variables:

# Override config directory
export XDG_CONFIG_HOME="$HOME/my-configs"

# Override data directory
export XDG_DATA_HOME="$HOME/my-data"

# Now config is in: $HOME/my-configs/lm-studio-bench/defaults.json
# Now results are in: $HOME/my-data/lm-studio-bench/results/

FAQ

Q: Where are my benchmark results stored?

A: ~/.local/share/lm-studio-bench/results/

If you pass --output-dir, report files (JSON/CSV/HTML/PDF) are written there. The SQLite cache databases still live in the user results directory.

Q: Where are the SQLite databases stored?

~/.local/share/lm-studio-bench/results/benchmark_cache.db
~/.local/share/lm-studio-bench/results/model_metadata.db

Q: Where do I put custom configuration?

A: ~/.config/lm-studio-bench/defaults.json

Only include fields you want to override from project defaults.

Q: Where are user presets stored?

A: ~/.config/lm-studio-bench/presets/

Built-in readonly presets (default_classic, default_compatibility_test, default as a legacy alias, quick_test, high_quality, resource_limited) are not stored as files.

Readonly preset names cannot be overwritten or deleted by user presets, including the alias default.

rm ~/.config/lm-studio-bench/defaults.json

Q: How do I backup my data?

A: Backup these directories:

# Configuration
tar -czf lms-bench-config.tar.gz ~/.config/lm-studio-bench/

# Results and cache
tar -czf lms-bench-data.tar.gz ~/.local/share/lm-studio-bench/

Q: What about logs?

A: Logs are stored in:

~/.local/share/lm-studio-bench/logs/

This includes benchmark, web app, tray, and launcher logs.

LM Studio Benchmark Docs