Install qBittorrent on TrueNAS Scale

qBittorrent on TrueNAS Scale gives you a headless torrent client with a web UI, running in a Docker container that persists across reboots — and the whole setup takes about five minutes.

What it is

qBittorrent is an open-source BitTorrent client built on libtorrent-rasterbar. Running it on TrueNAS Scale means you get a persistent, self-updating torrent client that lives on your NAS alongside your media libraries — no dedicated machine, no Windows bloat, no port forwarding headaches beyond a single container.

The LinuxServer.io image is the de facto standard: it bundles qbittorrent-nox (headless, web-UI only) with sensible defaults, automatic restarts, and clean volume mounts. On TrueNAS Scale, you deploy it as a custom app pointing at your existing datasets.

The hard part: volume mounts and permissions

The actual Docker command is trivial. The hard part is getting the mount paths right so qBittorrent can write downloads to your NAS dataset and read its own config across restarts.

The mistake everyone makes: mounting /mnt/downloads to the wrong container path, or forgetting that TrueNAS datasets have their own ACLs. If the container writes to /downloads but your host path is /mnt/media/torrents, you get silent permission errors and an empty download folder.

How to install it

Method 1: Custom Docker App (recommended)

TrueNAS Scale lets you deploy any Docker image as a custom app. This gives you full control over mount paths, environment variables, and networking.

1. Create the config directory: bash mkdir -p /mnt/apps/qbittorrent/config

2. Open the TrueNAS web UI → Apps → Discover Apps → Custom App (Docker Compose)

3. Paste this YAML:

yaml services: qbittorrent: image: lscr.io/linuxserver/qbittorrent:latest container_name: qbittorrent restart: unless-stopped environment: - PUID=1000 - PGID=1000 - TZ=Europe/London - WEBUI_PORT=8080 ports: - 8080:8080 - 6881:6881/tcp - 6881:6881/udp volumes: - /mnt/apps/qbittorrent/config:/config - /mnt/downloads:/downloads

1. Click Deploy. The container pulls the image and starts within seconds.

2. Find the initial password:

3. Go to the qBittorrent app → Workloads → View Logs
4. Search for the line containing password

5. The username is admin; the password is randomly generated

6. Log in at http://<your-nas-ip>:8080

Method 2: TrueNAS Community App Store

Some community-maintained app catalogs include a qBittorrent chart. These pre-configure the mount paths and add a settings UI, but you lose direct control over the Docker Compose. If you prefer a GUI-driven setup, this works — just make sure to set the download path to /mnt/downloads in the storage configuration.

Configuration that matters

Download path

In the qBittorrent web UI, go to Settings → Downloads:

The /downloads path inside the container maps to /mnt/downloads on the host. Whatever you set here is where files actually land on your TrueNAS pool.

Networking

For most home setups, bridge networking with explicit port mapping is fine. If you need UPnP or are running a VPN tunnel on the NAS, host networking simplifies things.

Permissions (TrueNAS ACLs)

If your TrueNAS dataset uses ACLs (the default on Scale), you need to grant the container user write access:

# Quick fix via CLI (if ACLs are disabled):
chmod -R 775 /mnt/downloads
chown -R 1000:1000 /mnt/downloads

# If ACLs are enabled (via TrueNAS UI):
# Datasets → /mnt/downloads → Edit Permissions
# Add ACL entry for user/group 1000 with Read/Write/Execute

The LinuxServer image runs as PUID=1000 PGID=1000 by default. If your TrueNAS admin user is also UID 1000, everything lines up. If not, match the PUID/PGID to your dataset's owner.

Speed limits and connection settings

What I'd tell anyone building this

• The initial password is random. It is not adminadmin anymore. Check the container logs immediately after deployment — Workloads → View Logs → search for password. If you miss it, you can reset it by deleting /mnt/apps/qbittorrent/config/qBittorrent/qBittorrent.conf and restarting.

• Mount paths must match the container's expected paths. The LinuxServer image expects /config and /downloads. If you mount to /data or /torrents, qBittorrent will not see your files. Read the image's README before changing mount paths.

• The download folder is on your NAS, not in the container. /mnt/downloads on the host is /downloads in the container. Files written here persist across container restarts, updates, and TrueNAS reboots. The container's ephemeral layer is not for storage.

• VPN integration is a separate concern. If you want all torrent traffic through a VPN, run a Gluetun sidecar container and route qBittorrent's traffic through it. This is a separate Docker Compose file, not a setting in qBittorrent itself.

• Updates are automatic but require a container restart. Pull the new image, recreate the container. Your /config and /downloads mounts are untouched — only the container image is replaced.

Get it

Links:

• qBittorrent official site
• LinuxServer.io qBittorrent image
• TrueNAS Scale documentation
• qBittorrent Web UI (after installation)

Quick install (Docker Compose):

services:
  qbittorrent:
    image: lscr.io/linuxserver/qbittorrent:latest
    container_name: qbittorrent
    restart: unless-stopped
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Europe/London
      - WEBUI_PORT=8080
    ports:
      - 8080:8080
      - 6881:6881/tcp
      - 6881:6881/udp
    volumes:
      - /mnt/apps/qbittorrent/config:/config
      - /mnt/downloads:/downloads

After deploy:

# Find the initial password:
docker logs qbittorrent 2>&1 | grep password

# Or via TrueNAS UI:
# Apps → qbittorrent → Workloads → View Logs → search "password"

Log in at http://<nas-ip>:8080 with username admin and the password from the logs. Change it immediately.