Run and Configure Tunarr: Environment Variables and Flags

Once Tunarr is installed, you can tune its behavior through environment variables and command-line flags. All options listed below apply regardless of whether you run Tunarr in Docker or as a standalone binary. Docker users should prefer environment variables set in their Compose file or docker run command.

Configuration Reference

Server

Environment Variable	CLI Flag	Default	Description
`TUNARR_DATABASE_NAME`	`--database`	`''`	Path where Tunarr writes its data. Do not set this in Docker — use a bind mount pointed to `/config/tunarr` instead.
`TUNARR_SERVER_PORT`	`--port` / `-p`	`8000`	Port the Tunarr server listens on. When using Docker, prefer a port mapping rather than setting this variable.
`TUNARR_BIND_ADDR`	N/A	`0.0.0.0`	Network interface Tunarr binds to. By default, Tunarr listens on all interfaces. This rarely needs to be changed.
`TUNARR_SERVER_TRUST_PROXY`	`--trust_proxy`	`false`	Enables trust proxy mode for deployments behind a reverse proxy.

Logging

Environment Variable	CLI Flag	Default	Description
`TUNARR_LOG_LEVEL`	N/A	`info`	Log verbosity. Valid values: `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `silent`. Overrides the UI setting.
`LOG_DIRECTORY`	N/A	(data dir)	Custom directory for log files. Defaults to the Tunarr data directory.

Streaming

Environment Variable	CLI Flag	Default	Description
`TUNARR_SESSION_CLEANUP_DELAY_SECONDS`	N/A	`15`	Seconds to wait before cleaning up a transcode session after the last client disconnects.

Search (Meilisearch)

Environment Variable	CLI Flag	Default	Description
`TUNARR_MEILISEARCH_PATH`	N/A	(auto-detected)	Path to the Meilisearch binary. Tunarr searches common locations automatically if not set.
`TUNARR_SEARCH_PORT`	N/A	(random available)	Port for the embedded Meilisearch instance.
`TUNARR_SEARCH_MAX_MEMORY`	N/A	(unlimited)	Maximum memory for Meilisearch indexing (e.g. `1024Mb`, `2Gb`). See Meilisearch docs.
`TUNARR_SEARCH_MAX_INDEXING_THREADS`	N/A	(all cores)	Maximum threads for Meilisearch indexing. Useful for limiting CPU usage on shared hosts.
`TUNARR_SEARCH_REDUCE_INDEXER_MEMORY_USAGE`	N/A	`true`	Reduces Meilisearch memory consumption during indexing. See Meilisearch docs. May impact file storage. Not available on Windows.
`TUNARR_DISABLE_SEARCH_SNAPSHOT_IN_BACKUP`	N/A	`false`	When `true`, excludes the Meilisearch snapshot from backups. The search index will be rebuilt from scratch on restore.

Artwork

Environment Variable	CLI Flag	Default	Description
`TUNARR_PROXY_ARTWORK`	N/A	`false`	When `true`, Tunarr proxies artwork requests through itself rather than redirecting clients to the media server URL. Useful when clients cannot reach your media server directly (e.g. behind a firewall or on a different network segment).

Transcoding

Environment Variable	CLI Flag	Default	Description
`TUNARR_TONEMAP_ENABLED`	N/A	`false`	Enables experimental HDR-to-SDR tonemapping when HDR source content is detected. See HDR Tonemapping.
`TUNARR_DISABLE_VULKAN`	N/A	`false`	Disables Vulkan-based tonemapping in the CUDA pipeline. Use if Vulkan is unavailable or causing stream failures; Tunarr will fall back to software tonemapping.
`TUNARR_DISABLE_VAAPI_PAD`	N/A	`false`	Disables hardware pad filters (`pad_vaapi` / `pad_opencl`) for VAAPI and falls back to software padding. Use if hardware padding causes artifacts or errors on your hardware.

Performance

Environment Variable	CLI Flag	Default	Description
`TUNARR_USE_WORKER_POOL`	N/A	`false`	Enables an experimental worker thread pool for background tasks.
`TUNARR_WORKER_POOL_SIZE`	N/A	(CPU count)	Number of threads in the worker pool. Recommended: no more than the number of CPUs on the host.

Debug

Environment Variable	CLI Flag	Default	Description
`TUNARR_SERVER_PRINT_ROUTES`	`--print_routes`	`false`	Prints all server routes at startup. Useful for debugging routing issues.

Hardware Transcoding

Tunarr supports hardware-accelerated transcoding via Nvidia NVENC, VAAPI (Intel/AMD), and Intel QuickSync. Enabling hardware acceleration in Docker requires passing the GPU device through to the container.

Nvidia NVENC
VAAPI / Intel QSV

The recommended approach for Nvidia GPUs is to install and configure the Nvidia Container Toolkit on your host.Docker Compose:

version: '3.8'
services:
  tunarr:
    image: chrisbenincasa/tunarr:latest
    container_name: tunarr
    ports:
      - ${TUNARR_SERVER_PORT:-8000}:8000
    environment:
      - TUNARR_LOG_LEVEL=${TUNARR_LOG_LEVEL:-INFO}
      - NVIDIA_VISIBLE_DEVICES=all
      - TZ=America/New_York
    volumes:
      - /path/to/tunarr/data:/config/tunarr
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu, video, utility]

Docker CLI:

docker run \
    --runtime nvidia \
    -v "$(pwd)"/tunarr:/config/tunarr \
    -e "TZ=America/New_York" \
    -p 8000:8000 \
    chrisbenincasa/tunarr

For VAAPI and Intel QuickSync, mount /dev/dri from the host into the container.Docker Compose:

version: '3.8'
services:
  tunarr:
    image: chrisbenincasa/tunarr:latest
    container_name: tunarr
    ports:
      - ${TUNARR_SERVER_PORT:-8000}:8000
    environment:
      - TUNARR_LOG_LEVEL=${TUNARR_LOG_LEVEL:-INFO}
      - TZ=America/New_York
    # Pass all render devices to the container
    devices:
      - /dev/dri:/dev/dri
    volumes:
      - /path/to/tunarr/data:/config/tunarr

Docker CLI:

docker run \
  -v "$(pwd)"/tunarr:/config/tunarr \
  --device /dev/dri:/dev/dri \
  -e "TZ=America/New_York" \
  -p 8000:8000 \
  chrisbenincasa/tunarr:latest

Running as a Service (Standalone Binary)

When using the standalone binary, it is strongly recommended to run Tunarr as a background service so it starts automatically and restarts on failure.

systemd (Linux)
launchd (macOS)
NSSM (Windows)

Follow these steps to install Tunarr as a systemd service:

Create the installation directory

sudo mkdir /opt/tunarr
sudo mkdir /opt/tunarr/streams

Move the binaries

Move both the Tunarr binary and the bundled Meilisearch binary to /opt/tunarr. Replace the source paths with the locations of your downloaded files.

sudo mv tunarr-linux-x64 /opt/tunarr/tunarr-linux-x64
sudo mv meilisearch /opt/tunarr/meilisearch

On every update, you must replace both the Tunarr and Meilisearch binaries.

Create the service file

sudo nano /etc/systemd/system/tunarr.service

Paste the following service definition and replace YOUR_USER and YOUR_GROUP with the Linux user and group you want Tunarr to run as:

[Unit]
Description=Tunarr
Wants=network-online.target
After=network-online.target

[Service]
Type=simple
WorkingDirectory=/opt/tunarr
ExecStart=/opt/tunarr/tunarr-linux-x64
ExecReload=pkill -INT tunarr-linux-x64
ExecStop=pkill -INT tunarr-linux-x64
KillMode=process
Restart=always
RestartSec=15

# Replace these values!
User=YOUR_USER
Group=YOUR_GROUP

StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

Press Ctrl+O then Enter to save, then Ctrl+X to exit.

Enable and start the service

sudo systemctl daemon-reload
sudo systemctl enable tunarr.service
sudo systemctl start tunarr

Save the following configuration to ~/Library/LaunchAgents/tunarr.xml. Replace /Path/to/tunarr with the directory where you installed the Tunarr binaries — somewhere stable like $HOME/.local/bin rather than your Downloads folder. Also replace USER_TO_RUN_TUNARR_AS and the HOME path accordingly.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.tunarr.server.app</string>
    <key>Program</key>
    <string>/Path/to/tunarr/tunarr</string>
    <key>WorkingDirectory</key>
    <string>/Path/to/tunarr</string>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardErrorPath</key>
    <string>/Path/to/tunarr/error.log</string>
    <key>StandardOutPath</key>
    <string>/Path/to/tunarr/output.log</string>
    <key>UserName</key>
    <string>USER_TO_RUN_TUNARR_AS</string>
    <key>HOME</key>
    <string>/Path/to/home</string>
</dict>
</plist>

Load the agent to start Tunarr immediately:

launchctl load ~/Library/LaunchAgents/tunarr.xml

NSSM is the recommended way to run Tunarr as a background Windows service.

Install NSSM

Download NSSM and unzip it. Place nssm.exe (from the win64 folder) into C:\Program Files\nssm\. Add C:\Program Files\nssm to your system PATH environment variable.

Open the NSSM installer

Open Command Prompt as Administrator and run:

nssm install

The NSSM configuration window will open. Set the service name at the bottom to Tunarr.

Configure the Application tab

In the Application tab:

Path — Full path to your Tunarr executable, e.g. C:\Program Files\tunarr\tunarr.exe
Startup directory — Directory containing the executable, e.g. C:\Program Files\tunarr
Arguments — Leave blank, or add --port 8001 if port 8000 is already in use.

Configure the Details tab

In the Details tab, set the Display name to Tunarr, add a description, and leave Startup type as Automatic.

Install the service

Click Install service. Tunarr will now start automatically with Windows.

Updating Tunarr under NSSM:

Open Services from the Start menu, right-click Tunarr, and click Stop.
Replace tunarr.exe and meilisearch.exe with the updated binaries.
Right-click Tunarr in Services and click Start.

If you are converting an existing standalone Tunarr installation to an NSSM service, note that NSSM runs under a different user context. Your data previously stored in %APPDATA%\tunarr must be copied to C:\Windows\System32\config\systemprofile\AppData\Roaming\tunarr for the service to pick it up.

Get Started

Media Sources

Channels

Scheduling

Library & Clients

Configuration

Help

Run and Configure Tunarr: Environment Variables and Flags

Configuration Reference

Server

Logging

Streaming

Search (Meilisearch)

Artwork

Transcoding

Performance

Debug

Hardware Transcoding

Running as a Service (Standalone Binary)

Build docs developers (and LLMs) love

Get Started

Media Sources

Channels

Scheduling

Library & Clients

Configuration

Help

Documentation Index

​Configuration Reference

​Server

​Logging

​Streaming

​Search (Meilisearch)

​Artwork

​Transcoding

​Performance

​Debug

​Hardware Transcoding

​Running as a Service (Standalone Binary)

Build docs developers (and LLMs) love

Configuration Reference

Server

Logging

Streaming

Search (Meilisearch)

Artwork

Transcoding

Performance

Debug

Hardware Transcoding

Running as a Service (Standalone Binary)