🇬🇧 English · 🇫🇷 Français

Applies to Hydranos 4.4.

This page is a weekend runbook for replacing qBittorrent with Hydranos without breaking Sonarr, Radarr, autobrr or cross-seed. You install Hydranos next to qBittorrent, import the library, hand over seeding, repoint your tools, check, and keep a way back. At the end you know what carries over, what does not, and how to roll back. Terms: Concepts and Glossary.

flowchart TD
    S1["1. Install Hydranos next to qBittorrent"] --> T1{"Web UI on port 8199 answers?"}
    T1 -- yes --> S2["2. Create categories with the same names"]
    S2 --> S3["3. Pause the tools, tag, import, stopped"]
    S3 --> T3{"Preview finds the data?"}
    T3 -- no --> FIX["Fix path mapping, Re-check paths"]
    FIX --> T3
    T3 -- yes --> S4["4. Stop qBittorrent, start in Hydranos"]
    S4 --> T4{"Seeding, no tracker errors?"}
    T4 -- yes --> S5["5. Point Sonarr and Radarr at Hydranos"]
    S5 --> T5{"Test passes, a grab imports?"}
    T5 -- yes --> S6["6. autobrr and cross-seed"]
    S6 --> T6{"Inject test seeds without recheck?"}
    T6 -- yes --> KEEP["Keep qBittorrent stopped, not deleted, for a while"]
    T1 -- no --> RB["Rolling back"]
    T4 -- no --> RB
    T5 -- no --> RB
    T6 -- no --> RB

Hydranos speaks the qBittorrent WebUI API (the qBittorrent shim, /api/v2/* on port 8199), so Sonarr, Radarr, autobrr and cross-seed keep their "qBittorrent" download client type. The shim covers what these tools need to add, list, stop, start, recategorise and delete torrents. It is not a full qBittorrent.

Your qBittorrent settings, one by one. Engine-level keys are set under Config › Advanced settings (default.toml) › Session Hoard (or Session Race), apply live, and are explained on Queue, Share and Speed Limits.

Absent in 4.4: search, selective download (file priority 0), alternative speed limits, multiple users. A client calling a missing endpoint gets a 404; the calls Hydranos has but cannot honour (priority 0, queue positions, rename) answer 409 with the reason.

Example: five downloads at a time, and a release stalled at 99 % does not hold a slot. Imported torrents and Sonarr's grabs land in hoard (Step 2), so set it in Session Hoard (active_downloads and the three figures are number fields, dont_count_slow_torrents a toggle), then Save settings: it applies at the next queue pass. Or in the file, but a hand edit is only read at the next start (or the next save from the UI):

[hoard]
active_downloads = 5               # live from Session Hoard or an API; queueing is not needed for this one
dont_count_slow_torrents = true    # a download under the threshold for the timer stops counting
slow_torrent_dl_rate_threshold = 2 # KiB/s
slow_torrent_inactive_timer = 60   # seconds

A slow download keeps running; it only stops holding a slot, so more than five can run at once. A torrent you stopped yourself never counts. A client can also set the ceiling with app/setPreferences max_active_downloads, which writes it into every local engine, race included. More: Example: keep 5 downloads running.

What the import carries over, per torrent: the .torrent file (exported from qBittorrent), the category name, the tags, the save path (after path mapping), the stopped state, completion (complete torrents whose data is found skip the hash check), and the lifetime uploaded/downloaded totals, so the ratio Hydranos shows in its own lists continues. It does not carry seeding time, the date added, speed or share limits, file priorities, sequential download, RSS feeds and rules, or any qBittorrent setting: set those again with the table above. Because seeding time starts from zero, a seeding-time limit and the tracker's Minimum seed are counted from the import for the whole library.

Install with the page for your platform: Docker, Linux (bare metal) or Windows (overview and ports on Installation and First Run). Leave qBittorrent running: the import reads its WebUI.

Ports. Hydranos uses 8199 (web UI and APIs, TCP), 16171 (race) and 16172 (hoard), each TCP and UDP. Check that qBittorrent's WebUI port and listen port are different from these on the same host.

Paths. This is the step that decides whether your library seeds at once or re-downloads. Hydranos must see the data at a real path, and Sonarr/Radarr must be able to reach the paths Hydranos reports (content_path = save path + torrent name). The simplest setup: mount the same host folder at the same container path qBittorrent used. If qBittorrent saw /downloads, give Hydranos /downloads too (fragment; the full compose file is on Docker):

services:
  hydranos:
    image: ghcr.io/kheopsian/hydranos:v4.4.1
    volumes:
      - ./hydranos-config:/config
      - /srv/media/downloads:/downloads   # same host folder, same container path as qBittorrent

Then you need no path mapping anywhere. If the paths cannot match, the import wizard has a path mapping (Step 3) and Sonarr/Radarr need a remote path mapping (Step 5); both have a filled-in example below.

First run, in three lines. Open http://<host>:8199 from your home network, before you open any port to the internet. Create the admin account on the Welcome to Hydranos screen (Create account, password of 8 characters or more), and note the API key under Config › Advanced settings (default.toml) › General › api_key. Details: Installation and First Run.

Right after sign-in, a window Import an existing library may open by itself. Click Skip for now: create categories first (Step 2). The wizard stays available under Config › Advanced settings (default.toml) › Import › Import…: despite the "Advanced settings" name, that is where Step 3 starts.

Hydranos refuses an add when the category is unknown and the client sends no save path. Create one Hydranos category per category your tools use, with exactly the same name (names are case-sensitive): Categories › + New › Name, Mode, Save Path › Save. Check the name twice: a rename later relabels the torrents in Hydranos, but every tool keeps sending the old name until you change it there too (see Categories and Routing).

Sonarr's and Radarr's Post-Import Category (e.g. tv-imported) is a category name too: leave it empty in Step 5, or create it here as well. Sonarr sets it with setCategory, which does not check that the category exists: a missing one leaves an orphaned label (see Categories and Routing).

If unsure, file your categories as Hoard. Race is for racing fresh uploads, and the race drain can delete race torrents together with their data, whether or not Sonarr has imported them yet. Torrents imported from qBittorrent always land in hoard, whatever their category's mode: with a Hoard category, your old library and Sonarr's new grabs sit in the same Hoard tab and behave the same way. With a Race category, the old tv torrents stay in Hoard and new tv grabs go to Race, under the drain. Details: Engines: Race and Hoard.

The import creates any missing category as hoard with the first save path it sees, after path mapping (the right-hand side of the preview), but it never changes a category that already exists, so the ones you create here win.

Before you import, do two things in your other tools:

1. Stop new grabs going to qBittorrent. In Sonarr, Radarr, autobrr and cross-seed, disable the qBittorrent download client (in Sonarr and Radarr: Settings › Download Clients, untick Enable). Otherwise a release grabbed after the import starts downloading in qBittorrent, Hydranos never gets it, and re-importing it later would put one torrent in both clients. They cannot grab until Step 5, so do Steps 3 to 5 in one sitting.
2. Tag what you stopped on purpose. Every imported torrent arrives stopped (the default below), so after the import nothing tells apart the torrents you had deliberately stopped in qBittorrent. Give them a tag in qBittorrent now (e.g. keep-stopped): tags carry over. Re-running the import later cannot add it, because a re-run skips every torrent already imported.

Then open Config › Advanced settings (default.toml) › Import › Import… (section Import from another client), and pick qBittorrent.

1. Import from qBittorrent: enter the WebUI URL as Hydranos reaches it, the qBittorrent username and password, then Preview. A bare host:port gets http:// added. Both qBittorrent 4.x and 5.x logins are understood. Only the URL is required (the username field starts at admin): Hydranos sends the username and password as typed, empty ones included, and stops only if qBittorrent answers Fails. or an error status (qBittorrent refused the login: …). Which URL:
   • http://qbittorrent:8080 only if both containers are on the same user-defined Docker network (a compose file puts its services on one).
   • Not sure? Use the host's LAN address and qBittorrent's published WebUI port, e.g. http://192.0.2.10:8080.
   • Hydranos inside a gluetun container: gluetun's firewall blocks the LAN by default. In gluetun the setting is usually called FIREWALL_OUTBOUND_SUBNETS: add your LAN range (e.g. 192.0.2.0/24). If qBittorrent also runs inside the same gluetun container, use http://localhost:8080. Not tested by the maintainer; see VPN and Egress.
2. Import preview shows the totals (complete, partial, carried upload), the categories it will create ("all imported as hoard"), and the path mapping: qBittorrent's folders on the left, what Hydranos should use on the right. There is one row per top-level save folder: a folder inside another listed folder is covered by it, and above 40 folders the list is folded onto parent folders. The preview also looks for the data of a sample of up to 64 torrents, at qBittorrent's paths unchanged. If it says no data was found, fix the right-hand paths and click Re-check paths: it checks that each right-hand folder exists for Hydranos (✓ or ✗), not each torrent's data.
3. Leave Import everything stopped, no announce until you start them ticked (the default). Nothing announces until Step 4.
4. Click Import {n} torrents. The progress line reads {done}/{total} · {complete} complete, data found · {check} to check or download · {failed} failed, then · {n} skipped and · {n} added stopped when there are any. The first two counts say what the data was, not whether it announces: with the box above ticked, every torrent added also counts as added stopped, and the end note says {n} torrents were added stopped, as chosen: nothing announces until you start them from the list. "Data found" means the content path exists after mapping; sizes and hashes are not checked.
5. When it reads Import complete, the torrents that failed are listed (name and error; past 200, …and {n} more, in the log.), and a Retry the {n} failed button runs only those again, without asking for the password: it is kept in memory until the next import or a restart, never written. Then click Close & reload. Back on the preview also keeps the password.

Path mapping, a filled-in example. One host folder, /srv/media/downloads, mounted at a different path in each container:

In the preview, the row reads /data/torrents/tv → change the right-hand side to /downloads/tv. Rule: take the left path, replace the container part of qBittorrent's volume (/data/torrents) with the container part of Hydranos' volume (/downloads). Re-check paths then shows ✓. The Hydranos category tv (Step 2) gets the same /downloads/tv as its save path.

sequenceDiagram
    actor You
    participant H as Hydranos
    participant Q as qBittorrent WebUI
    You->>H: Preview with URL, username, password
    H->>Q: POST /api/v2/auth/login
    H->>Q: GET /api/v2/torrents/info
    H-->>You: totals, categories, path rows, data test on up to 64
    opt a path row is wrong
        You->>H: Re-check paths with the edited mapping
        H-->>You: folder exists or not, per row
    end
    You->>H: Import N torrents
    H->>Q: log in and list again
    loop each torrent
        H->>Q: GET /api/v2/torrents/export?hash=HASH
        opt dropped connection, 429 or 5xx, or 401 or 403
            H->>Q: log in again after a 401 or 403, wait 1 s then twice as long, ask again, 4 attempts in all
        end
        alt export failed, or the add was refused
            H->>H: counted failed, listed, kept for a retry
        else already in any engine
            H->>H: counted skipped
        else complete in qBittorrent and content path exists
            H->>H: add to hoard in seed mode, no hash check
        else otherwise
            H->>H: add to hoard, hash-checked against the disk
        end
    end
    H-->>You: complete with data found, to check or download, failed, skipped, added stopped
    H->>H: record the provenance if at least one torrent was added
    opt some torrents failed
        You->>H: Retry the n failed
        H->>Q: log in again, then export only the failed ones
    end
    Note over H,Q: qBittorrent is only read, never changed

What the import does, exactly:

• qBittorrent is not modified. Hydranos only logs in, lists /api/v2/torrents/info and downloads each .torrent through /api/v2/torrents/export. Nothing is stopped, removed or changed on the qBittorrent side.
• Every imported torrent goes to the hoard engine, whatever the mode of its category.
• A torrent is added in seed mode (no hash check) only if it is complete in qBittorrent and its content path exists after mapping. Only existence is checked, not sizes. Anything else is hash-checked against what is on disk, even while stopped, and resumes from there.
• A torrent stopped in qBittorrent stays stopped, even if you untick the "Import everything stopped" box.
• Import does not fire "when a torrent is added" workflows.
• Re-running is safe: a torrent already in any engine is counted skipped and left as it is (tags, category and state are not updated).
• A busy qBittorrent does not cost you torrents. Each .torrent export is tried up to 4 times (wait 1 s, then doubled) after a dropped connection, a 429 or a 5xx; after a 401 or 403 Hydranos logs in again first, so a session that expires during a long import is renewed. A 404, or a 409 (no metadata yet in qBittorrent: a magnet that never fetched its metadata there), is not retried.
• If every torrent counts as failed, read the list at the end or the log line import: torrent not added; an export … http 404 means this qBittorrent does not offer the export endpoint, and (gave up after 4 attempts) means it kept failing. Fix the cause, then Retry the {n} failed (or POST /api/import/retry, which also works after a Transmission import).
• The import is remembered. An import that added at least one torrent records where the library came from: the Overview shows same counter · carried over from qBittorrent, and the Import an existing library window no longer opens at sign-in.

Coming from Transmission instead? Pick Transmission. Hydranos reads Transmission's config folder (the one holding torrents/ and resume/), so Transmission does not need to be running; if the folder is not visible to Hydranos, upload a .zip of it. Options: Create one category per destination folder and Import labels as tags (both ticked by default). Torrents with no resume file are skipped. The preview has path mapping rows but no Re-check paths button. Everything else above applies.

Never let both clients run the same torrent: two clients writing into one incomplete download corrupt it, and two peers from one address on the same torrent can upset a private tracker. So qBittorrent stops first, then Hydranos starts.

1. In qBittorrent, select all torrents and stop them. Then stop qBittorrent itself (its container or service) and disable its autostart, so it cannot come back on its own after a reboot. Keep its config and data: that is your rollback. In qBittorrent, stopped torrents normally stay stopped when it starts again.
2. In Hydranos, open Hoard. To leave your keep-stopped torrents out, right-click keep-stopped in the Tags list among the filters beside the table (click includes a tag, right-click excludes it). Press Ctrl+A: it selects every torrent the filter matches, not only the first 500 rows the list draws. Right-click › Start. Above 500 torrents Hydranos asks for confirmation; a progress panel follows the bulk task (see Jobs, Bulk Actions and Moving Data).
3. Watch the state chips: Checking while hash checks run, then Seeding, or Downloading for incomplete torrents. Tracker Error shows torrents whose tracker refused them: open one to read the message. Incomplete torrents beyond the engine's active_downloads (10 in the shipped [hoard], or the 5 of the example above) show Queued and start as slots free up (the queue runs every 30 s, so right after the bulk Start more downloads than the ceiling can run until its next pass; after a restart, its first pass comes about a minute in).

In Sonarr (and the same in Radarr): Settings › Download Clients. Add a new qBittorrent client and leave the old one in place, disabled since Step 3, until the checks pass. Field names below are Sonarr/Radarr v4's.

Click Test and save. Login answers Ok. or Fails.; a call without a session gets 403 Forbidden., which is what Sonarr and Radarr expect before they log in. In each indexer's settings, seed ratio and seed time now work. Whether the tool sends them with the add or through setShareLimits, they become the torrent's own share limits and the engine's share_limit_action (stop in the shipped file) applies, but only once the tracker's Minimum seed (Trackers › Edit, announce_min_seed_hours) is served. A tracker with no Minimum seed declared holds the limit for good (log share limit reached, held): declare 0 for a tracker without a seeding rule.

Remote path mapping, a filled-in example. Only needed when Sonarr sees the downloads at another path than Hydranos. With Hydranos mounting /srv/media/downloads at /downloads (Step 3 example) and Sonarr mounting it at /data/torrents, add under Settings › Download Clients › Remote Path Mappings:

Not tested by the maintainer. Mounting the same container path in every container avoids the mapping altogether, and Sonarr's hardlink imports need downloads and library on one mount anyway (Docker).

The sequence below is what Hydranos receives when Sonarr grabs a release.

sequenceDiagram
    participant S as Sonarr
    participant H as Hydranos shim
    participant P as Placement
    participant E as Engine
    S->>H: GET /api/v2/app/webapiVersion (no session)
    H-->>S: 403 Forbidden.
    S->>H: POST /api/v2/auth/login (username, password)
    H-->>S: Ok. and SID cookie
    S->>H: POST /api/v2/torrents/add (torrent or urls, category=tv)
    H->>P: category tv, savepath if sent
    alt no savepath, category unknown or without a save path, none set by setPreferences
        P-->>H: refused, no save path
        H-->>S: 400 Fails.
    else category tv known, with a save path
        P->>E: engine hoard if mode is hoard, else race
        H-->>S: 200 Ok.
    end
    loop while Sonarr tracks the download
        S->>H: GET /api/v2/torrents/info?category=tv
        H-->>S: state downloading, stalledDL, checkingDL or queuedDL
        H-->>S: then uploading or stalledUP, progress 1, content_path
    end
    Note over S,H: ratio and uploaded are the real lifetime figures

Both use the same "qBittorrent" client type, host, port 8199 and credentials as above. Full per-application settings are on qBittorrent Shim and Automation; the points that matter for a migration:

• autobrr: magnets sent through urls work; Hydranos resolves the metadata in the background and answers Ok. at once. autobrr's reannounce option uses torrents/reannounce, which works. Rules based on ratio or upload see the real figures. Upload and download limits and the ratio and seed-time limits of an autobrr action are applied (same tracker guard as in Step 5).
• cross-seed: an inject with skip_checking=true is added in seed mode, without a hash check (a magnet too, once its metadata arrives). Every category cross-seed sends must exist in Hydranos with the mode you want: an unknown category with an explicit save path is accepted and lands in the race engine. With cross-seed's duplicate-categories option on, it usually sends a category ending in .cross-seed (e.g. tv.cross-seed): create it as Hoard too. cross-seed sees the torrents of every engine, each hash once, but it can only add to race or hoard (through the category's mode).

Re-enable these tools' download clients pointing at Hydranos only. The old qBittorrent clients stay disabled.

Optional, from a shell (replace 192.0.2.10 with your host):

If a grab fails with Fails., the category is usually missing or has no save path: check the Categories tab. The log line qbit add refused (qbit add: url refused for a magnet or a .torrent URL) gives the exact reason (also an unparsable .torrent, or a race add refused for disk space when add_block_enabled is on). More symptoms on Troubleshooting.

• Seed goals are subject to the tracker's minimum. Your tools see the real ratio and uploaded, and the limits they send are applied, but no share limit (theirs or the engine's) stops or removes a torrent before the tracker's Minimum seed is served, and none ever acts for a tracker with no Minimum seed declared (a torrent with no tracker at all is not held; Step 5). The action is the engine's share_limit_action, not a per-torrent choice. Seeding time is not imported, so time-based limits count from import day for the whole library. For rules share limits cannot express (per category, per tracker), a workflow on a timer can stop the torrent or delete the torrent; a new workflow is saved switched off: tick Enabled in the Workflows list. See Workflows.
• Categories created by a client (through createCategory) are always hoard, with whatever save path the client sent; a name that already exists answers 409 Category already exists and is left as you set it. An empty save path makes every add to that category fail. Check the Categories tab after a Test.
• setCategory is a label change only: Sonarr's post-import category does not move files or change engine.
• A torrent held by two engines is listed once, as its first engine's copy (race before hoard, then the extra engines).
• setPreferences applies part of what it receives: share limits, speed caps, max_active_downloads, the slow-torrent rule, save_path, and dht/pex/lsd (at the next start); other keys answer 200 and are logged as having no effect. queueing itself is only switched in Hydranos. Some fields stay constant (seeds in properties, availability, the qBittorrent version). The full fidelity table is on qBittorrent Shim and Automation.
• Refused or missing calls: priority 0 in filePrio, rename and the queue-position calls (topPrio, bottomPrio, increasePrio, decreasePrio) answer 409; sync/maindata always sends a full update; search, renameFile, renameFolder, editTracker, setSuperSeeding, setAutoManagement, alternative speed limits and log/* answer 404.

The import only reads qBittorrent, so your qBittorrent library, settings and resume data are as you left them. Undo in reverse order:

1. Save what only Hydranos has. Torrents grabbed while Hydranos was in charge are not in qBittorrent. Select them (on Hoard, click one row then Shift+click another to select the range; on Race, where Ctrl+A does nothing, the same Shift+click), right-click › Download .torrent files (.zip) › Keep trackers.
2. Stop Hydranos itself (docker stop hydranos, or as described on Operating Hydranos). This stops every engine, race and hoard, at once. Do not use Remove + delete files: the data is shared with qBittorrent. For the same reason, keep share_limit_action at stop until you are sure you will not roll back.
3. Bring qBittorrent back: re-enable its autostart, start it, then start its torrents (leave your deliberately stopped ones). Add the saved .torrent files with qBittorrent's skip hash check option.
4. In Sonarr, Radarr, autobrr and cross-seed, re-enable the old qBittorrent client, disable or delete the Hydranos one, and delete any remote path mapping you added for Hydranos in Step 5.

If you moved data with Set location… or Change category + move files › in Hydranos (or a tool called setLocation), qBittorrent will not find it at the old path: move it back or set the new location in qBittorrent.