qBittorrent

Feature-rich BitTorrent client with Web UI and integrated search

qBittorrent is a free, open-source BitTorrent client with a clean Qt interface and powerful Web UI for remote administration. QuickBox Pro deploys qBittorrent as the headless qbittorrent-nox binary from QuickBox compiled packages, built with Qt6, libtorrent-rasterbar 2.x, and Boost 1.83+ for maximum performance and compatibility. The installed version is resolved dynamically from the compiled-packages manifest for your distro, so you always get the latest available build.

Installation

Install from the Dashboard

Open App Dashboard → Package Management (/dashboard?mode=packages), find qBittorrent in the catalog (browse Download Clients or search), and click Install. The dashboard streams the install log live and qBittorrent appears in your Application Control panel when it finishes. Reinstall and Remove are in the same Package Management panel. To update, use the amber Update badge on the qBittorrent row in the App Dashboard.

While the server does not have qBittorrent yet, an administrator’s install dialog lets them pick the version — the available builds are resolved from the compiled-packages catalog for your distro, and the matching libtorrent-rasterbar, Boost, and Qt6 dependencies are paired automatically. Without a pick, the latest available build installs. Once qBittorrent is on the server, every install and reinstall uses the server’s version, and only an administrator’s update changes it. A regular user whose group allows qBittorrent installs it directly once it is on the server. While the server does not have qBittorrent yet, the button reads Request install and an administrator approves the first install with the version they pick; see Install requests. See Channels & Versions for how version resolution and beta channels work.

What you see and can manage is gated by your account: admins manage any user’s apps; regular users manage their own. For the full package flow see App Management.

Install from the CLI (automation)

The CLI runs the same install and is suited to automation and scripting. While the server has no qBittorrent, an install without a version gets the latest available build, and -o '<version>' pins a specific build from the compiled-packages manifest. Once it has qBittorrent, every install and reinstall uses the server’s version and a different -o is refused:

qb install qbittorrent -u username
qb install qbittorrent -u username -o '5.1.4'

Accessing qBittorrent

After installation, access qBittorrent at:

Login credentials:

• Username: Your QuickBox username
• Password: Your QuickBox password (hashed with PBKDF2)

Browser Download Index

In addition to the qBittorrent Web UI, QuickBox installs a per-user browser file index that lists the finished-download folder of your qBittorrent in a dark-themed fancyindex view. Useful for quickly grabbing a single finished file without loading the torrent client.

• The listing is the folder set as Default Save Path in qBittorrent, not a fixed location. Change it in the qBittorrent settings and QuickBox re-renders the index on its own, usually within seconds, with an hourly check as a safety net. If the folder can’t be served (it is a symlink, it is outside your home folder, /mnt and /media, it doesn’t exist, or the web server can’t read it), the index keeps serving the default folder and the dashboard shows a note beginning “Showing the default folder.” See Open download folder for each note.
• Removing qBittorrent keeps your finished downloads. qb remove qbittorrent deletes the client’s configuration and data but never the download folder or what is inside it, and the remove output names the folder it kept. Reinstalling writes your save path back into the fresh configuration.
• The index is stitched together per user: if you also have rTorrent, Deluge, Transmission, NZBGet, or SABnzbd installed, their completed-download locations are appended into the same username.dlindex.conf so each client gets its own URL. It is one shared browse-index config covering all of that user’s download clients.
• The feature has no service of its own — it is pure nginx. If the page fails to load — returns a 502 or 404, shows blank, or errors — while the rest of the dashboard works normally, the per-user config is broken or missing. Rebuild it with qb fix dlindex -u username (one user) or qb fix dlindex (all users). See the Download Clients overview and the qb fix reference.

Initial Configuration

1. Configure Download Paths

• Settings → Downloads → Default Save Path: /home/username/torrents/qbittorrent/downloads
• Completed torrents can be moved to a different folder automatically
• Watch folder configured at /home/username/torrents/qbittorrent/watch

2. Connect to *arr Applications (Optional)

If using Sonarr, Radarr, or other *arr applications:

1. In your *arr app, go to Settings → Download Clients → Add (+)
2. Select qBittorrent from the list
3. Enter connection details:
   • Host: 127.0.0.1
   • Port: Your Web UI port (check ~/.config/qBittorrent/qBittorrent.conf)
   • Username: Your QuickBox username
   • Password: Your QuickBox password
   • Category: Create categories like sonarr, radarr as needed
4. Test and save

3. Enable Search Plugins (Optional)

• Tools → Search → Search plugins → Check for updates
• Install plugins for your preferred torrent sites
• Search functionality accessible via Web UI

VPN routing for qBittorrent

QuickBox Pro supports routing qBittorrent’s network traffic through a WireGuard VPN tunnel, isolating BitTorrent traffic from the rest of your server’s internet activity. This is managed from System → VPN Control in the dashboard.

Why route qBittorrent through VPN?

How to enable

1. Navigate to System → VPN Control in the dashboard (admin access required).
2. Ensure at least one WireGuard peer configuration is uploaded and active.
3. Scroll to the App-Scoped Routing card and select qBittorrent.
4. Choose a WireGuard peer config from the dropdown.
5. Click Enable Routing.

Once routing is active, qBittorrent’s traffic exits through the VPN tunnel. The /qbittorrent/ URL and dashboard tile continue to work normally — the dashboard handles internal connectivity automatically.

Port forwarding and connectability

When qBittorrent is routed, downloading, seeding and your tracker ratio keep working either way, from the VPN exit IP. Whether other peers can start a connection to you depends on your VPN provider. Port forwarding works with the WireGuard backend. A client routed over OpenVPN works the same way as the no-forwarding case below: downloading, seeding and ratio are unaffected. The routing card shows a Port forwarding section for qBittorrent:

• ProtonVPN: pick a P2P server and generate the WireGuard config with NAT-PMP (port forwarding) turned on; the dashboard recognises it and leases a forwarded port automatically, keeping it renewed. The port shows read-only with an Active, Renewing, or Failed status, and qBittorrent’s listen port is kept in step with it. If a config is not recognised (for example one you edited), open its popover and set Provider override to ProtonVPN.
• AirVPN: add a forwarded port in your AirVPN account, then enter it in Forwarded port (from your provider account) when you enable routing.
• NordVPN: this VPN provider does not forward ports. Downloading, seeding and your tracker ratio all keep working. Your tracker may show you as not connectable, which only means other peers can’t start a connection to you. You may seed to slightly fewer peers, because two peers that are both not connectable can’t reach each other. A provider that forwards a port (ProtonVPN, AirVPN) removes that limit.

The dashboard pins the port automatically. You can also set the peer listen port yourself with qb manage software -o listen-port (see the manage command reference).

Kill switch behavior

The kill switch stops qBittorrent if the VPN connection goes stale, ensuring no BitTorrent traffic leaks to your server’s real IP address. The default threshold for qBittorrent is 30 minutes — longer than the 10-minute default for media servers.

This longer default exists because torrent sessions are long-lived. WireGuard handshakes can stall briefly during normal operation (especially on residential-grade VPN providers), and an aggressive threshold would trigger false kill switch events that interrupt active downloads unnecessarily.

You can adjust the threshold between 60 seconds and 24 hours from the kill switch settings panel in VPN Control. When auto-recovery is enabled, the dashboard attempts to restore routing automatically after a kill switch event.

For full VPN Control configuration details — including kill switch tuning and peer management — see the VPN Control documentation.

Service Management

qBittorrent runs as a systemd service for reliability and automatic startup.

systemctl status qbittorrent@username     # Check status
systemctl restart qbittorrent@username    # Restart service
journalctl -u qbittorrent@username -f     # View live logs
systemctl enable qbittorrent@username     # Start on boot
systemctl disable qbittorrent@username    # Prevent auto-start

Troubleshooting

qBittorrent Won’t Start

journalctl -u qbittorrent@username -f

Check for port conflicts:

grep -i 'WebUI\\Port' ~/.config/qBittorrent/qBittorrent.conf
# Default: 11001

Web UI Not Accessible

Permission Issues

qb fix permissions -u username
systemctl restart qbittorrent@username

Configuration Reset

# Backup current configuration
cp ~/.config/qBittorrent/qBittorrent.conf ~/.config/qBittorrent/qBittorrent.conf.backup
 
# Remove configuration (will be regenerated)
rm ~/.config/qBittorrent/qBittorrent.conf
 
# Restart service
systemctl restart qbittorrent@username

Best Practices

FAQ

Related Applications

Additional Resources