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, Update, and Remove are available from the same panel.

The version and all dependencies (libtorrent-rasterbar, Boost, Qt6) are resolved automatically for your distribution — there is nothing to pick. 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:

qb install qbittorrent -u username

Accessing qBittorrent

After installation, access qBittorrent at:

https://your-server-ip/qbittorrent/

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 contents of your qBittorrent download directory in a dark-themed fancyindex view. Useful for quickly grabbing a single finished file without loading the torrent client.

https://your-server-ip/username.qbittorrent.downloads

• The listing path matches the qBittorrent save directory, including the downloads/ and watch/ subfolders.
• 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. Enter your Peer Listen Port (see below — this step is required).
5. Choose a WireGuard peer config from the dropdown.
6. 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.

Peer Listen Port — required step

To find or set your peer port in qBittorrent:

1. Open the qBittorrent Web UI at https://your-server/qbittorrent/.
2. Go to Settings (gear icon in the top toolbar).
3. Select the BitTorrent (or Connection) tab.
4. Under Listening Port, note the port number — or enter a new one in the 1024–65535 range.
5. Click Save if you changed the port, then restart qBittorrent: systemctl restart qbittorrent@username.
6. Enter this same port in the VPN Control Peer Listen Port field before clicking Enable Routing.

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