Whisparr v3 Install Guide: What Changes and How to Set It Up

Understand Whisparr v2 vs v3, decide which branch fits you, and follow a clean Whisparr v3 install with Docker tags, fresh setup steps and safety notes. — a practical, beginner-friendly walkthrough.

Whisparr v3 Install Guide: What Changes and How to Set It Up — feature illustration

Search for Whisparr and you will quickly run into two version numbers: v2 and v3. They are not simply “old” and “new” builds of the same thing — they are separate development branches with different data models. This guide explains the practical differences and walks through a clean Whisparr v3 install without putting an existing library at risk.

Whisparr v2 vs Whisparr v3 in plain words

The v2 branch is the established line most existing guides describe, and it is the branch the official archive linked from our download section tracks. The v3 branch is the newer generation, built with a reworked data model and an updated API. In day-to-day terms that changes how items are represented in the library and how third-party tools talk to the app.

Because both branches evolve, we intentionally avoid printing feature tables that might go stale. The honest rule: check the official source for current branch status before you commit, then decide based on how you use the app.

Which branch should you pick?

  • Pick v2 if you want the path with the most existing documentation and community answers, or you are matching a tutorial written for v2.
  • Pick v3 if you are starting fresh, want the newer architecture, and are comfortable with the occasional rough edge of a newer branch.
  • Running both is fine. They are separate apps with separate config folders — a common approach is keeping v2 in production while trying v3 on a different port.

Installing Whisparr v3 with Docker (recommended)

The cleanest v3 install is a fresh container with a v3 image tag and its own config volume:

services:
  whisparr-v3:
    image: <whisparr-image-with-v3-tag>
    container_name: whisparr-v3
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Asia/Karachi
    ports:
      - "6970:6969"
    volumes:
      - ./config-v3:/config
      - /data:/data
    restart: unless-stopped

Notice two deliberate choices: a separate config folder (./config-v3) so nothing touches an existing v2 database, and a different host port (6970) so both UIs can be open at once. Everything else follows our standard compose configuration.

First-run setup on v3

  1. Open the UI on your chosen port and enable authentication.
  2. Add your root folder under Media Management and switch renaming on.
  3. Connect indexers — if you use Prowlarr, add the v3 instance as a new application so indexers sync to it separately.
  4. Connect your download client with a category distinct from your v2 instance (for example whisparr3) so their queues never collide.
  5. Add a couple of test items and confirm they import before adding your full list.

Moving from v2 to v3

Do not copy a v2 database into a v3 config folder and hope — the data models differ. The safe route is a fresh v3 install that points at the same library root, letting v3 scan and match your existing organized files. Keep the v2 instance stopped (not deleted) until you are satisfied that v3 sees your library correctly.

Back up your config folder before any branch experiment. It is one small folder, and it is the difference between an annoyance and a disaster.

Download Now

Related guides