pgsql-jellyfin/PATH_CONFIGURATION_GUIDE.md

Jellyfin Path Configuration Guide

Overview

All major paths in Jellyfin are now fully configurable through three methods: configuration file, command-line options, or environment variables. This allows you to customize where Jellyfin stores its data, logs, cache, configuration, and temporary files.

Configuration Methods

Jellyfin supports three ways to configure paths (in priority order):

1. Configuration File (NEW!)

Create a startup.json file with your path configurations. See FILE_BASED_STARTUP_CONFIG.md for details.

Example:

{
  "Paths": {
    "DataDir": "/var/lib/jellyfin",
    "ConfigDir": "/etc/jellyfin",
    "CacheDir": "/var/cache/jellyfin",
    "LogDir": "/var/log/jellyfin",
    "TempDir": "/var/tmp/jellyfin"
  }
}

2. Command-Line Options

Pass options when starting Jellyfin.

Example:

jellyfin --datadir /var/lib/jellyfin --logdir /var/log/jellyfin

3. Environment Variables

Set environment variables in your shell or systemd service.

Example:

export JELLYFIN_DATA_DIR=/var/lib/jellyfin
export JELLYFIN_LOG_DIR=/var/log/jellyfin

Priority Order

When a path is configured in multiple places, Jellyfin uses this priority (highest to lowest):

1. Command-line options (highest priority)
2. Environment variables
3. Configuration file (startup.json)
4. Default values (lowest priority)

This allows you to:

• Set defaults in a configuration file
• Override system-wide with environment variables
• Override temporarily with command-line options

Available Path Configurations

1. Program Data Directory (Database Files)

Purpose: Main directory for database files and application data

• Configuration File: Paths:DataDir in startup.json
• Command Line: -d, --datadir <path>
• Environment Variable: JELLYFIN_DATA_DIR
• Default:
  • Windows: %LocalAppData%\jellyfin
  • Linux/Unix: $XDG_DATA_HOME/jellyfin or ~/.local/share/jellyfin
  • macOS: ~/Library/Application Support/jellyfin

Example:

# Configuration file (startup.json)
{
  "Paths": {
    "DataDir": "/var/lib/jellyfin"
  }
}

# Command line
jellyfin --datadir /var/lib/jellyfin

# Environment variable
export JELLYFIN_DATA_DIR=/var/lib/jellyfin

2. Configuration Directory

Purpose: User settings, pictures, and configuration files

• Configuration File: Paths:ConfigDir in startup.json
• Command Line: -c, --configdir <path>
• Environment Variable: JELLYFIN_CONFIG_DIR
• Default:
  • Windows/macOS: {datadir}/config
  • Linux/Unix: $XDG_CONFIG_HOME/jellyfin or ~/.config/jellyfin

Example:

# Configuration file
{
  "Paths": {
    "ConfigDir": "/etc/jellyfin"
  }
}

# Command line
jellyfin --configdir /etc/jellyfin

# Environment variable
export JELLYFIN_CONFIG_DIR=/etc/jellyfin

3. Cache Directory

Purpose: Image cache, metadata cache, and other temporary cached data

• Configuration File: Paths:CacheDir in startup.json
• Command Line: -C, --cachedir <path>
• Environment Variable: JELLYFIN_CACHE_DIR
• Default:
  • Windows/macOS: {datadir}/cache
  • Linux/Unix: $XDG_CACHE_HOME/jellyfin or ~/.cache/jellyfin

Example:

# Configuration file
{
  "Paths": {
    "CacheDir": "/var/cache/jellyfin"
  }
}

# Command line
jellyfin --cachedir /var/cache/jellyfin

# Environment variable
export JELLYFIN_CACHE_DIR=/var/cache/jellyfin

4. Log Directory

Purpose: Application log files

• Configuration File: Paths:LogDir in startup.json
• Command Line: -l, --logdir <path>
• Environment Variable: JELLYFIN_LOG_DIR
• Default: {datadir}/log

Example:

# Configuration file
{
  "Paths": {
    "LogDir": "/var/log/jellyfin"
  }
}

# Command line
jellyfin --logdir /var/log/jellyfin

# Environment variable
export JELLYFIN_LOG_DIR=/var/log/jellyfin

5. Temp Directory ⭐ NEW

Purpose: Temporary files created during transcoding and other operations

• Configuration File: Paths:TempDir in startup.json
• Command Line: -t, --tempdir <path>
• Environment Variable: JELLYFIN_TEMP_DIR
• Default: {system_temp}/jellyfin (e.g., /tmp/jellyfin on Linux)

Example:

# Configuration file
{
  "Paths": {
    "TempDir": "/var/tmp/jellyfin"
  }
}

# Command line
jellyfin --tempdir /var/tmp/jellyfin

# Environment variable
export JELLYFIN_TEMP_DIR=/var/tmp/jellyfin

6. Web Client Directory

Purpose: Location of the Jellyfin web client files

• Configuration File: Paths:WebDir in startup.json
• Command Line: -w, --webdir <path>
• Environment Variable: JELLYFIN_WEB_DIR
• Default:
  1. Searches for wwwroot folder in solution root (development)
  2. Falls back to {appdir}/jellyfin-web

Example:

# Configuration file
{
  "Paths": {
    "WebDir": "/usr/share/jellyfin/web"
  }
}

# Command line
jellyfin --webdir /usr/share/jellyfin/web

# Environment variable
export JELLYFIN_WEB_DIR=/usr/share/jellyfin/web

Usage Examples

Using Command Line Options

# Windows
jellyfin.exe --datadir "C:\ProgramData\Jellyfin" --logdir "C:\Logs\Jellyfin" --tempdir "D:\Temp\Jellyfin"

# Linux
jellyfin --datadir /var/lib/jellyfin --logdir /var/log/jellyfin --tempdir /var/tmp/jellyfin --cachedir /var/cache/jellyfin

Using Environment Variables

# Linux/macOS - Add to ~/.bashrc or /etc/environment
export JELLYFIN_DATA_DIR=/var/lib/jellyfin
export JELLYFIN_CONFIG_DIR=/etc/jellyfin
export JELLYFIN_CACHE_DIR=/var/cache/jellyfin
export JELLYFIN_LOG_DIR=/var/log/jellyfin
export JELLYFIN_TEMP_DIR=/var/tmp/jellyfin
export JELLYFIN_WEB_DIR=/usr/share/jellyfin/web

# Windows - Set in PowerShell or System Properties
$env:JELLYFIN_DATA_DIR="C:\ProgramData\Jellyfin"
$env:JELLYFIN_LOG_DIR="C:\Logs\Jellyfin"
$env:JELLYFIN_TEMP_DIR="D:\Temp\Jellyfin"

Systemd Service (Linux)

Create or edit /etc/systemd/system/jellyfin.service:

[Unit]
Description=Jellyfin Media Server
After=network-online.target

[Service]
Type=simple
User=jellyfin
Group=jellyfin
Environment="JELLYFIN_DATA_DIR=/var/lib/jellyfin"
Environment="JELLYFIN_CONFIG_DIR=/etc/jellyfin"
Environment="JELLYFIN_CACHE_DIR=/var/cache/jellyfin"
Environment="JELLYFIN_LOG_DIR=/var/log/jellyfin"
Environment="JELLYFIN_TEMP_DIR=/var/tmp/jellyfin"
Environment="JELLYFIN_WEB_DIR=/usr/share/jellyfin/web"
ExecStart=/usr/bin/jellyfin

[Install]
WantedBy=multi-user.target

Priority Order

When determining which path to use, Jellyfin follows this priority:

1. Command-line option (highest priority)
2. Environment variable
3. Default value (lowest priority)

This allows you to:

• Set system-wide defaults via environment variables
• Override on a per-run basis with command-line options
• Fall back to sensible defaults if nothing is specified

Directory Permissions

Ensure the user running Jellyfin has appropriate permissions:

# Linux example - create directories and set permissions
sudo mkdir -p /var/lib/jellyfin /etc/jellyfin /var/cache/jellyfin /var/log/jellyfin /var/tmp/jellyfin
sudo chown -R jellyfin:jellyfin /var/lib/jellyfin /etc/jellyfin /var/cache/jellyfin /var/log/jellyfin /var/tmp/jellyfin
sudo chmod 755 /var/lib/jellyfin /etc/jellyfin /var/cache/jellyfin /var/log/jellyfin /var/tmp/jellyfin

Benefits

Performance

• Place temp directory on fast storage (SSD/NVMe) for transcoding performance
• Put cache on separate disk to reduce I/O contention
• Use different mount points for logs vs data

Storage Management

• Separate data across different partitions/disks
• Use network storage for backups while keeping temp on local fast storage
• Easier to manage disk space quotas

Security

• Follow OS security best practices (e.g., /var hierarchy on Linux)
• Set appropriate permissions per directory type
• Separate user data from system configuration

Containerization

• Map volumes to specific paths
• Follow container best practices (ephemeral temp, persistent data)
• Easier Docker/Podman volume mounting

Backup & Maintenance

• Backup only important directories (data, config) and skip cache/temp
• Easier to exclude temporary files from backups
• Simplified cleanup of cache and temp directories

Docker Example

version: '3.8'
services:
  jellyfin:
    image: jellyfin/jellyfin:latest
    environment:
      - JELLYFIN_DATA_DIR=/data
      - JELLYFIN_CONFIG_DIR=/config
      - JELLYFIN_CACHE_DIR=/cache
      - JELLYFIN_LOG_DIR=/log
      - JELLYFIN_TEMP_DIR=/temp
    volumes:
      - /host/jellyfin/data:/data
      - /host/jellyfin/config:/config
      - /host/jellyfin/cache:/cache
      - /host/jellyfin/log:/log
      - /fast-storage/jellyfin/temp:/temp
    ports:
      - "8096:8096"

Verification

After starting Jellyfin, check the logs to verify paths are set correctly:

[INF] Program data path: /var/lib/jellyfin
[INF] Config directory path: /etc/jellyfin
[INF] Cache path: /var/cache/jellyfin
[INF] Log directory path: /var/log/jellyfin
[INF] Temp directory path: /var/tmp/jellyfin
[INF] Web resources path: /usr/share/jellyfin/web

Notes

• All paths are created automatically if they don't exist (permissions allowing)
• Paths are normalized to absolute paths internally
• Relative paths are resolved from the current working directory
• Changes require a restart to take effect
• Command-line help: jellyfin --help