QBittorrent: Difference between revisions

Latest revision as of 11:43, 31 October 2025

qBittorrent is an open source and cross-platform BitTorrent client written in C++, Qt and Python (optional search engine), using libtorrent-rasterbar library.

It is fast, stable and light, supports unicode and provides an integrated search engine. It comes with UPnP/NAT-PMP port forwarding, encryption, FAST extension and PeX support.

Installation

There are two packages in official repositories to install qBittorrent with:

qBittorrent — Qt graphical interface and #Web interface.

https://github.com/qbittorrent/qBittorrent || qbittorrent

qBittorrent-nox — Without graphical interface (nox -> no X server).

https://github.com/qbittorrent/qBittorrent || qbittorrent-nox

Note Although qbittorrent-nox does not directly depend on Xorg, its dependency qt6-base currently depends on X facilities and Mesa, which would increase about 300M installation size. To minimize the installation size, install qt6-base-headless^AUR instead of qt6-base before installing qbittorrent-nox

Configuration

A configuration file is created at ~/.config/qBittorrent/qBittorrent.conf upon running the program the first time.

Autostart

Tip To modify the settings (i.e. port) use an environment variable (for port it is QBT_WEBUI_PORT) by using a drop-in file for its systemd unit. Run qbittorrent-nox --help to learn more about other environment variables (this information is not stated in the manual).

Running as the package-created qbt user

As of qbittorrent-nox-5.0.4-3, an unprivilleged user, qbt, will be created upon installation. The package also ships with qbittorrent-nox.service in which this user is hardcoded.

To see the OTP to the WebGUI upon starting the daemon, review the output of: systemctl status qbittorrent-nox.

In order to prevent the legal disclaimer from being written to journalctl, edit /var/lib/qbittorrent/.config/qBittorrent/qBittorrent.conf and add the following:

[LegalNotice]
Accepted=true

Running as any user

Another option is to run the qbittorrent-nox@.service in which QBittorrent will run as the user defined.

Search engine

The optional search engine may be enabled through the menu View > Search Engine, which opens the Search tab.

Search plugins

Default trackers can be added/enabled in the Search tab by opening the tracker window with Search plugins... (bottom right) and pressing Check for updates. More unofficial search plugins can be found here.

Web interface

Default location

By default, qBittorrent will listen on all interfaces on port 8080. Thus it is accessible at http://HOST_IP:8080.

Note HTTPS is not enabled by default, so https://HOST_IP:8080 is not accessible. See the upstream documentation for instructions on creating and using self-signed TLS certificates.

Default username & password

The default username is admin and the default password for versions before 5.0.0 is adminadmin. Versions 5.0.0 and above generate a random password visible in console until manually saved to prevent unauthorized access. See here for more information related to this change.

Allow access without username & password

In a home environment, it is often desirable to allow access to the Web UI without having to input a username and password. This can be configured in the Web UI itself after logging in using the default username and password.

Alternatively, to avoid logging in for the first time, add this section to ~/.config/qBittorrent/qBittorrent.conf:

[Preferences]
WebUI\AuthSubnetWhitelist=192.168.1.0/24
WebUI\AuthSubnetWhitelistEnabled=true
WebUI\UseUPnP=false

The above configuration items will:

Allow clients logging in from 192.168.1.x to access the Web UI without having to enter a username and password.
Disable UPnP for the Web UI, so that the Web UI will not be accessible from outside the network.

After that, reload qbittorrent-nox@username.service.

Reverse proxy configuration

nginx

Refer to qbittorrent wiki

Themes

Unofficial themes

Troubleshooting

qBittorrent stopped downloading (after reopening)

Sometimes, the nova component of the search engines does not terminate after closing qbittorrent. Doing so, it binds the corresponding port, if one was set. Thus, one has to manually terminate the nova plugins:

 $ killall nova

@@ Line 1: / Line 1: @@
-{{Lowercase_title}}
+{{Lowercase title}}
 [[Category:BitTorrent]]
 [https://www.qbittorrent.org/ qBittorrent] is an open source and cross-platform [[BitTorrent]] client written in [[C++]], [[Qt]] and [[Python]] (optional search engine), using {{Pkg|libtorrent-rasterbar}} library.
-It is fast, stable and light, supports unicode and provides an integrated search engine. It comes with UPnP port forwarding / NAT-PMP, encryption ([[Vuze]] compatible), FAST extension (main‐line) and PeX support ([[uTorrent]] compatible).
+It is fast, stable and light, supports unicode and provides an integrated search engine. It comes with UPnP/NAT-PMP port forwarding, encryption, FAST extension and PeX support.
 == Installation ==
@@ Line 11: / Line 11: @@
 * {{App|qBittorrent|[[Qt]] graphical interface and [[#Web interface]].|https://github.com/qbittorrent/qBittorrent|{{Pkg|qbittorrent}}}}
 * {{App|qBittorrent-nox|Without graphical interface (nox -> no X server).|https://github.com/qbittorrent/qBittorrent|{{Pkg|qbittorrent-nox}}}}
+{{Note|Although {{Pkg|qbittorrent-nox}} does not directly depend on [[Xorg]], its dependency {{Pkg|qt6-base}} currently depends on X facilities and [[Mesa]], which would increase about 300M installation size. To minimize the installation size, install {{AUR|qt6-base-headless}} instead of {{Pkg|qt6-base}} before installing {{Pkg|qbittorrent-nox}}}}
 == Configuration ==
@@ Line 18: / Line 20: @@
 === Autostart ===
-If you install {{Pkg|qbittorrent-nox}}, you will get a systemd unit template {{ic|qbittorrent-nox@.service}}. QBittorrent will run as a specific user if you [[enable/start]] {{ic|qbittorrent-nox@''username''.service}},see also [https://github.com/qbittorrent/qBittorrent/wiki/Running-qBittorrent-without-X-server-(WebUI-only,-systemd-service-set-up,-Ubuntu-15.04-or-newer) ].
+{{Tip|To modify the settings (i.e. port) use an environment variable (for port it is QBT_WEBUI_PORT) by using a [[drop-in file]] for its systemd unit. Run {{ic|qbittorrent-nox --help}} to learn more about other environment variables (this information is not stated in the manual).
+}}
+==== Running as the package-created qbt user ====
+As of {{Pkg|qbittorrent-nox}}-5.0.4-3, an unprivilleged user, qbt, will be created upon installation. The package also ships with {{ic|qbittorrent-nox.service}} in which this user is hardcoded.
+To see the OTP to the WebGUI upon starting the daemon, review the output of: {{ic|systemctl status qbittorrent-nox}}.
+In order to prevent the legal disclaimer from being written to journalctl, edit {{ic|/var/lib/qbittorrent/.config/qBittorrent/qBittorrent.conf}} and add the following:
+ [LegalNotice]
+ Accepted=true
-QBittorrent will run as the user {{ic|''username''}}. The default download folder will be the user's {{ic|Downloads}} directory, but this can be reconfigured later.
+==== Running as any user ====
-{{Tip|
+Another option is to run the {{ic|qbittorrent-nox@.service}} in which QBittorrent will run as the user defined.
-* If you are running it as a accessible service [[Users and groups#Example adding a user|create a user]] called qbittorrent and make it run under it, and make the service restart on exit as the program have exit button.
-* To modify the settings (i.e. port) you can add an environment variable (for port it is QBT_WEBUI_PORT) by using a [[drop-in file]] for its systemd unit. Run {{ic|qbittorrent-nox --help}} to learn more about other environment variables (this information is not stated in the manual).
-}}
 == Search engine ==
@@ Line 33: / Line 43: @@
 === Search plugins ===
-Default trackers can be added/enabled in the ''Search'' tab by opening the tracker window with ''Search plugins...'' (bottom right) and pressing ''Check for updates''. More unofficial search plugins can be found [https://github.com/qbittorrent/search-plugins/wiki/Unofficial-search-plugins here].
+Default trackers can be added/enabled in the ''Search'' tab by opening the tracker window with ''Search plugins...'' (bottom right) and pressing ''Check for updates''. More unofficial search plugins can be found [https://plugins.qbittorrent.org here].
 == Web interface ==
@@ Line 39: / Line 49: @@
 === Default location ===
-By default, qBittorrent will listen on all [[Network_configuration#Network_interfaces|interfaces]] on port 8080. Thus it is accessible at {{ic|http://HOST_IP:8080}}.
+By default, qBittorrent will listen on all [[Network configuration#Network interfaces|interfaces]] on port 8080. Thus it is accessible at {{ic|http://HOST_IP:8080}}.
-{{Note|HTTPS is not enabled by default, so {{ic|https://HOST_IP:8080}} is not accessible.}}
+{{Note|HTTPS is not enabled by default, so {{ic|https://HOST_IP:8080}} is not accessible. See the [https://github.com/qbittorrent/qBittorrent/wiki/Linux-WebUI-setting-up-HTTPS-with-self-signed-SSL-certificates upstream documentation] for instructions on creating and using self-signed TLS certificates.}}
 === Default username & password ===
@@ Line 66: / Line 76: @@
 === Reverse proxy configuration ===
 ==== nginx ====
 Refer to [https://github.com/qbittorrent/qBittorrent/wiki/NGINX-Reverse-Proxy-for-Web-UI qbittorrent wiki]
@@ Line 77: / Line 89: @@
 == Troubleshooting ==
+=== qBittorrent stopped downloading (after reopening) ===
+Sometimes, the {{ic|nova}} component of the search engines does not terminate after closing {{Pkg|qbittorrent}}. Doing so, it binds the corresponding port, if one was set. Thus, one has to manually terminate the {{ic|nova}} plugins:
+  $ killall nova
 == See also ==