In this guide, you will be learning how to install and run qBittorent on the Raspberry Pi.
qBittorent is one of the most popular torrent clients that you can use on the Pi.
It has become known for its relatively stable platform and good feature set that works well on limited-resource devices like the Raspberry Pi.
In addition to showing you how to install qBittorrent, we will also show you how you can set up and configure its web interface.
Setting up the web interface allows you to control your Raspberry Pi’s qBittorrent from another device easily.
Thanks to the web interface you can easily use this client on a headless Raspberry Pi. Headless being a device that does not have a monitor, keyboard, or mouse.
Below you can view all of the equipment we used for running qBittorrent on the Raspberry Pi.
Micro SD Card (8GB+)
Installing qBittorent to the Raspberry Pi
Before we can use qBittorrent, we need to show you how to install the torrent client to your Raspberry Pi.
Installing this torrent client is a fairly straightforward process, so you will have the software up and running in no time.
1. Before installing qBittorrent, let us make sure our Raspberry Pi uses up-to-date packages.
Doing this ensures that we are less likely to run into issues when we install the client.
To perform an upgrade of packages, you will need to use the following two commands.
sudo apt update sudo apt full-upgrade
2. Next, we can install qBittorrent on to our Raspberry Pi.
In this case, we have two separate commands that we can use to install the software.
What version you want to use depends entirely on how you are using your Raspberry Pi.
qBittorrent for the Desktop Raspberry Pi
The first command is for those that want to use the full desktop version of the software.
This version of qBittorent is heavier and cannot be used for those running a headless Raspberry Pi.
sudo apt install qbittorrent
qBittorrent for a Headless Raspberry Pi
The second command will allow you to install a command-line version of qBittorrent.
This version is ideal for those running a headless environment as it gives you easy access to the web interface.
sudo apt install qbittorrent-nox
3 At this point, you should now have the qBittorrent software installed on your Raspberry Pi.
Setting up qBittorent using the Desktop Interface
In this section, we will show you various things, including how to open qBittorrent on your Raspberry Pi and how to enable the web interface.
For this section, you will need to have a mouse and keyboard attached to your Raspberry Pi.
If you are using a headless setup, be sure to skip to our next setting up section.
Opening qBittorrent on the Raspberry Pi
Before we can configure qBittorrent, we need to first open up the software on our Raspberry Pi.
1. On the Raspberry Pi interface, you need to click the icon in the screen’s top-left corner.
Clicking this icon will bring up the start menu on your screen.
2. Within the start menu, you will need to hover over the “
Internet” option (1.).
Hovering over this option will expose a couple of applications. In the drop down menu, identify “
qBittorrent” then click it (2.).
3. When you first run qBittorrent on your Raspberry Pi, you will see a legal notice that you need to read before continuing.
If you are fine with what is mentioned in the legal notice, click the “I Agree” button to continue.
4. You should now have the qBittorrent client running on your Raspberry Pi.
You can now proceed to add your torrents and download them from your device.
If you would like to manage your torrents remotely, it is possible to make use of the software’s web UI.
Enabling the Web UI through the Client Software
This section, will show you how to use the qBittorrent client’s interface to enable its web interface.
1. With the qBittorrent software opened on your Raspberry Pi, click the “
Tools” option in the top toolbar (1.).
In the dropdown box, click the “
Preferences” option (2.)
2. Within the “Preferences” menu, we need to change to the “
Web UI” tab by clicking the icon in the left sidebar (1.).
Once you have switched to the Web UI menu, click the “
Web User Interface” checkbox to enable it (2.).
3. After you have enabled the web user interface, you will be able to modify it’s settings.
You should change the username and password you will use to login into the interface (1.).
Once you have set your authentication details, click the “
Apply” button to finalize your setup (2.).
To learn how to access and use this web interface you can check out the “
Using the qBittorrent Web Interface” section below
Setting up qBittorent using the Command-Line
Using qBittorrent from the Raspberry Pi’s command line is a reasonably straightforward process thanks to the Nox client we are using.
In this section, we are going to show you several things. First is how to run the torrent client from the Raspberry Pi’s terminal.
Then we will show you how to set up a service so that qBittorent will start at boot. Finally, we will introduce you to the web interface.
Before we start, one thing to note is that the command-line version of qBittorrent is mainly designed to be configured through its web interface and not the command line itself.
Starting qBittorrent using the Raspberry Pi’s Terminal
In this section, you will see how simple it is to start the web interface only version of qBittorrent on your Raspberry Pi.
1. To launch the command line version of qBittorrent on your Raspberry Pi, all you need to do is run the following command.
2. Upon running qBittorrent from the command line, you will be met with the following message.
This message tells you that you need to control the torrent client from the web interface and not your Raspberry Pi’s command-line.
It will also tell you the currently defined user name for the web UI administrator. By default, this username will be
******** Information ******** To control qBittorrent, access the Web UI at http://localhost:8080 The Web UI administrator user name is: admin
3. The current problem with how we are running qBittorrent on the Raspberry Pi is that as soon as the current terminal session is closed, the client will close as well.
To get around this, we will create a service that will handle the operation of the client.
You can quit out of the torrent client by pressing CTRL + C.
Running qBittorrent as a Service
In this next section, we will create a service that will run and manage the qBittorrent client on the Raspberry Pi.
1. Before creating the service, we should first create a user for the client to operate under.
The main reason we are going to do this comes down to improving the Raspberry Pi’s security.
Let us use the following useradd command to create our new user. For this guide, we are going to call this new user
sudo useradd -r -m qbittorrent
With the command, you will notice that we use the “
--system) argument. This argument tells the command that it should make this user a system user.
Additionally, we use the “
-m” argument to tell the command that it should create a home directory for the user.
This means that the user can’t be logged in to and acts as a system only user.
2. To ensure that we can access the files created by our new “
qbittorrent” user, we will add the “
pi” user to its group.
To do this, we will make use of the
usermod command. Run the following command on your Raspberry Pi to add the
pi user to the
sudo usermod -a -G qbittorrent pi
-a” argument tells the command we want to add a new attribute to a user. The “
-G” argument says that we are adding a group.
3. Finally, we can move on to creating the service itself.
For writing this service on our Raspberry Pi for the qBittorrent software, we will make use of the nano text editor.
sudo nano /etc/systemd/system/qbittorrent.service
4. Within this file, we want to enter the following lines of text.
These lines dictate how the service manager runs qBittorrent.
[Unit] Description=qBittorrent After=network.target [Service] Type=forking User=qbittorrent Group=qbittorrent UMask=002 ExecStart=/usr/bin/qbittorrent-nox -d --webui-port=8080 Restart=on-failure [Install] WantedBy=multi-user.target
There is a couple of things that we should point out with this service that we have created.
First is that the qBittorrent software will be run under the user and group that we created earlier.
Additionally, we apply a “
UMask” to the user so that all files created by this user will hold the following Linux permission, “
This permission means that the owner and group can read and write all files created by this user.
Lastly, we pass in the path to the qBittorrent executable with a few arguments.
The first is “
-d“, which tells the program we want to run it as a “daemon”.
Secondly, we use the “
--webui-port” argument to pass in the port that we want the Web UI to be available through.
5. With everything entered, save the file by pressing CTRL + X, then Y, followed by the ENTER key.
6. Now that we have created the file, we can now start our newly created qBittorrent service.
sudo systemctl start qbittorrent
7. We can verify that qBittorrent is now running on our Raspberry Pi by using the following command.
sudo systemctl status qbittorrent
If the torrent client is running as intended, you should see the following text appear from this command.
Active: active (running)
8. Finally, now that we know that the qBittorrent service works, we can make it start when our Raspberry Pi boots.
You can enable the bootup functionality by running the following command on your device.
sudo systemctl enable qbittorrent
Using the qBittorrent Web Interface
In this section, we will show you how to access the qBittorrent web interface as well as where to find its option page
For those running a headless Raspberry Pi setup, this is the only way of managing your torrents.
Accessing the Web Interface for qBittorrent
Accessing qBittorrent’s web UI is a fairly straightforward process. All you need is a web browser and the IP address of your Raspberry Pi.
1. At this point, you should have the qBittorrent web interface enabled, whether through the desktop client or by using the command-line version of qBittorrent.
To get to the interface, you need to go to the following address in your favorite web browser.
Make sure you replace “
[YOUR IP ADDRESS]” with the local IP address of your Raspberry Pi.
http://[YOUR IP ADDRESS]:8080
2. When accessing your qBittorrent web interface, you will need to login (1.).
If you haven’t changed the authentication details, the default username for this interface is “
admin“, and the default password is “
Once you have entered the correct details, you can click the “
Login button (2.).
3. You can now use the web interface to manage both the torrent client itself and your torrents.
Configuring qBittorrent through the Web Interface
Luckily configuring qBittorrent its quite a simple process, especially through its web interface.
1. To get to the options, you need to click the “
Tools” button in the top toolbar (1.).
In the dropdown box, click the “
Options” button to open up the dialog box (2.).
2. Using the options dialog box (1.), you can configure almost every element of qBittorrent.
One of the first things you should configure with this interface is your username and password (2.).
Hopefully, at this point, you will now have successfully set up qBittorrent on your Raspberry Pi.
It is one of the best torrent clients for the Raspberry Pi and is perfect for a headless setup, thanks to its excellent web interface.
If you have run into any issues with this guide, or feel like something is missing, please leave a comment below.
Also, check out some of our other great Raspberry Pi projects to see what else you can do with your device.