| Jackie Sung | Linux | 4 min read
How to Install qBittorrent on CentOS, RHEL, Debian, and Ubuntu Server
Install qBittorrent-nox on a headless Linux server, run it with systemd, open the Web UI, and optionally place it behind NGINX.
qBittorrent is a clean, open-source BitTorrent client. On a server, the useful package is qbittorrent-nox: no desktop window, just the Web UI and a background process that can be managed with systemd.
This is an updated version of my old CentOS 8/RHEL 8 note. The CentOS/RHEL part is still here, but I have also added Debian and Ubuntu because that is where many small VPS boxes actually live.
Before You Start
Use a normal user for daily SSH work, and run commands with sudo. In the examples below, qBittorrent runs as a separate service user called qbtuser.
If you run this on a public VPS, do not expose the Web UI naked to the whole internet for long. At minimum, change the default password immediately. A reverse proxy, VPN, firewall allowlist, or private tunnel is much better.
Install on CentOS 8, RHEL 8, AlmaLinux, or Rocky Linux
CentOS 8 itself is end-of-life, so for a fresh machine I would use AlmaLinux, Rocky Linux, CentOS Stream, or a supported RHEL clone. For the package install, the important part is EPEL.
sudo dnf install -y epel-release
sudo dnf install -y qbittorrent-noxOn some RHEL 8 systems, epel-release is not available until CodeReady Builder is enabled. If the simple command above fails, use this path instead:
sudo dnf install -y dnf-plugins-core
sudo subscription-manager repos --enable codeready-builder-for-rhel-8-$(arch)-rpms
sudo dnf install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm
sudo dnf install -y qbittorrent-noxInstall on Debian
Debian includes qbittorrent-nox in the official package archive.
sudo apt update
sudo apt install -y qbittorrent-noxThat is the boring path, which is usually the best path on a server.
Install on Ubuntu
Ubuntu also includes qbittorrent-nox.
sudo apt update
sudo apt install -y qbittorrent-noxIf you specifically want a newer qBittorrent build than the Ubuntu archive provides, qBittorrent maintains an official stable PPA for supported Ubuntu releases.
sudo apt install -y software-properties-common
sudo add-apt-repository ppa:qbittorrent-team/qbittorrent-stable
sudo apt update
sudo apt install -y qbittorrent-noxFor a production server, I usually prefer the distro package unless I need a newer Web UI feature or a bug fix.
Create a Service User
Create a dedicated user. On Debian and Ubuntu:
sudo adduser --disabled-password --gecos "" qbtuserOn CentOS/RHEL-style systems:
sudo useradd -m -s /bin/bash qbtuserRun qBittorrent once as that user. This lets you accept the legal notice and see the initial Web UI login information.
sudo -u qbtuser -H qbittorrent-noxYou should see the Web UI address, usually http://localhost:8080. The administrator username is usually admin, and older/current distro builds commonly start with adminadmin as the password. If your qBittorrent build prints a temporary password instead, use the password shown in the terminal.
Press Ctrl-C after the first run. Then lock the service user out of direct shell login.
Debian and Ubuntu:
sudo usermod -s /usr/sbin/nologin qbtuserCentOS/RHEL:
sudo usermod -s /sbin/nologin qbtuserStart qBittorrent with systemd
Most modern packages include the template service qbittorrent-nox@.service. Check it first:
systemctl cat qbittorrent-nox@.serviceIf it exists, start qBittorrent as qbtuser and enable it at boot:
sudo systemctl enable --now qbittorrent-nox@qbtuser
systemctl status qbittorrent-nox@qbtuser --no-pagerUseful service commands:
sudo systemctl restart qbittorrent-nox@qbtuser
sudo systemctl stop qbittorrent-nox@qbtuser
sudo journalctl -u qbittorrent-nox@qbtuser -n 100 --no-pagerIf the package does not include a service template, create one:
[Unit]
Description=qBittorrent-nox service for %i
Documentation=man:qbittorrent-nox(1)
Wants=network-online.target
After=network-online.target nss-lookup.target
[Service]
Type=exec
User=%i
ExecStart=/usr/bin/qbittorrent-nox
Restart=on-failure
[Install]
WantedBy=multi-user.targetSave that file as /etc/systemd/system/qbittorrent-nox@.service, then reload and start:
sudo systemctl daemon-reload
sudo systemctl enable --now qbittorrent-nox@qbtuserOpen the Web UI
From your local browser, use:
http://your-server-ip:8080After logging in, go to Tools -> Options -> Web UI and change the password immediately.
If you use a firewall, open the port only when you really need direct access.
CentOS/RHEL with firewalld:
sudo firewall-cmd --add-port=8080/tcp --permanent
sudo firewall-cmd --reloadDebian/Ubuntu with UFW:
sudo ufw allow 8080/tcpFor a cleaner setup, keep qBittorrent bound to 127.0.0.1 and access it through a reverse proxy or VPN.
Optional NGINX Reverse Proxy
Here is a simple subdomain-style NGINX example. Replace qbt.example.com and the certificate paths with your own.
server {
listen 80;
server_name qbt.example.com;
return 301 https://$host$request_uri;
}
server {
listen 443 ssl http2;
server_name qbt.example.com;
ssl_certificate /etc/letsencrypt/live/qbt.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/qbt.example.com/privkey.pem;
location / {
proxy_pass http://127.0.0.1:8080/;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Real-IP $remote_addr;
}
}Then test and reload NGINX:
sudo nginx -t
sudo systemctl reload nginxIf you prefer a subpath like example.com/qbt/, use qBittorrent’s official NGINX reverse proxy notes. Subpath proxies need a little more care than a dedicated subdomain.
Quick Troubleshooting
Check whether qBittorrent is listening:
ss -lntp | grep 8080Check service logs:
sudo journalctl -u qbittorrent-nox@qbtuser -n 100 --no-pagerCheck the qBittorrent version:
qbittorrent-nox --versionIf login fails repeatedly, wait a bit before trying again. qBittorrent may temporarily ban an IP after too many failed Web UI login attempts.
