# Installing qBittorrent (Host Installation)

qBittorrent is the download engine of your media automation setup. It handles all torrent activity triggered by Radarr,
Sonarr, and Prowlarr. Installing it on the **host system** (not Docker) ensures optimal speed, stable paths, and maximum
compatibility.

This guide explains:

- What qBittorrent does in the media pipeline
- Why it should *not* run inside Docker in a real-world Pi/home server setup
- Why its configuration does **not** need to be moved to your external drive
- The installation script used to install and run qBittorrent as a systemd service

---

## 🌀 What Is qBittorrent?

qBittorrent is an open‑source torrent client featuring:

- Lightweight Web UI
- Fast download engine
- Built-in category and tagging support
- Excellent integration with Radarr & Sonarr
- Very low resource usage

It acts as the **download worker** for the entire Media Manager.

When Radarr or Sonarr find new media, they send the torrent to qBittorrent. Upon completion, ARR processes renaming and
file management.

---

## ❌ Why qBittorrent Should NOT Run in Docker

Though technically possible, running qBittorrent in Docker on low-power hardware like Raspberry Pi causes significant
issues:

### 1. Docker slows torrent hashing

- Torrenting requires intensive hashing and verifying large files
- Docker’s overlay filesystem adds overhead, causing slower hashing and higher CPU usage

### 2. Permissions become complicated

- Bind-mounted volumes in Docker cause UID/GID mismatches
- Sonarr/Radarr struggle to access or import completed downloads correctly
- On the host, file permissions behave predictably and natively

### 3. Stable real file paths are necessary

- qBittorrent expects actual Linux paths (e.g., `/mnt/omnissiah-vault/downloads`)
- Containers often abstract paths, confusing ARR’s automation

### 4. Performance is better on the host

- Download speeds, disk writes, and hashing all run faster without Docker’s overhead

**Conclusion:**

- **qBittorrent performs best installed directly on the host system.**

---

## 📦 Why qBittorrent Configuration Does NOT Need External HDD

Unlike Plex’s large metadata, qBittorrent stores only minor config files such as:

- Configuration settings
- Small torrent resume files
- A lightweight database

Typical config size: **2–20 MB** — negligible and stable.

Keeping qBittorrent config on your system’s internal OS disk is safe and recommended.

---

## ⚙️ Installation Script (Systemd Service)

## ⚙️ Installation Script

This tutorial uses an installation script that:

- Updates and upgrades system packages
- Installs qBittorrent-nox (the headless version)
- Creates a dedicated system user for qBittorrent
- Adds your normal user to the qBittorrent group for file access
- Creates a systemd service file to run qBittorrent as a background service
- Enables and starts the qBittorrent service to run at boot

After running the script, you can access qBittorrent’s Web UI and begin configuring your download settings.

### 📥 Download Script

👉 **[install-qbittorrent.sh](../scripts/shell/install-qbittorrent.sh)**

---

## 🚀 After Installation

Access the Web UI at:

```
http://<your_pi_ip>:8080
```

Default credentials:

```
username: admin
password: adminadmin
```

**Change your password on first login!**

- Configure download directories
- Add categories such as `movies` and `tv`
- Disable any unwanted torrenting features

ARR integration will be configured after the Docker-based ARR stack is deployed.

---

## ➡️ Next Step: Setup ARR Stack (Docker Compose)

Now that host-based components (Plex and qBittorrent) are ready, proceed to deploy the ARR stack via Docker Compose to
automate searching, downloading, and organizing your media.

Go to 👉 **[Setup Media Manager](setup-media-manager.md)**

---
