Installing Whisparr on TrueNAS SCALE

Run Whisparr on TrueNAS SCALE — a practical, beginner-friendly walkthrough.

Installing Whisparr on TrueNAS SCALE — feature illustration

TrueNAS SCALE is a natural home for Whisparr: your storage pool and your automation live on the same always-on box. The setup is straightforward as long as you do it in the right order — datasets first, permissions second, app last. Skipping ahead is where most permission headaches on TrueNAS come from.

Step 1 — Create the datasets

In Datasets, create a structure that keeps downloads and the organized library under one parent so hardlinks work:

tank/
├── apps/
│   └── whisparr        ← config lives here
└── data/
    ├── downloads/      ← download client output
    └── media/          ← organized library

The exact pool name does not matter; the single shared data parent does. If downloads and media sit on different datasets, every import becomes a slow full copy instead of an instant hardlink.

Step 2 — Set permissions once, properly

Create a dedicated user (or use the common convention of UID/GID 1000) and give it ownership of the apps/whisparr and data datasets via the ACL editor. Whatever IDs you choose here are the exact values you will type into the app as PUID and PGID. Mismatched IDs are the number one cause of “permission denied” errors on SCALE.

Step 3 — Deploy the app

You have two routes on SCALE:

  • App catalog: if a Whisparr app is available in the catalog you use, install it from the Apps section and fill in the storage and environment screens.
  • Custom app: otherwise, use Custom App and point it at a community Whisparr image — the same images covered in our Docker setup guide.

Either way, configure:

  • Environment: PUID and PGID from step 2, plus your timezone.
  • Port: web port 6969 (or another free host port).
  • Storage: host path /mnt/tank/apps/whisparr → /config, and host path /mnt/tank/data → /data.

Step 4 — Verify before you automate

Open http://truenas-ip:6969, enable authentication, add /data/media as your root folder and connect your download client (which must also write inside /data). Then run one test item end to end. On the file level, a successful hardlinked import is instant — if the import step takes as long as a copy, your paths cross dataset boundaries and need revisiting.

TrueNAS-specific tips

  • After a SCALE system update, apps occasionally redeploy — the /config host path is what preserves your database, so back that dataset up with a periodic snapshot task.
  • Snapshots of the config dataset before app updates give you one-click rollback.
  • Keep the app's resources modest; Whisparr is light and does not need large CPU or memory reservations.

Download Now

Related guides