Running qBittorrent using Docker

In this tutorial, we will be showing you how to install and run qBittorrent NOX using a Docker container.

qBittorrent is one of the best torrent clients known for being lightweight and feature-packed.

Thanks to qBittorrent NOX having its own web interface, it is a great torrent client for running within a Docker container.

An advantage to running this torrent client using Docker is that it is super easy to use the latest version. You can upgrade with a couple of commands rather than relying on your package repository to provide the new release.

We will use the official qBitttorrent NOX docker container, so you will always get the latest versions. Additionally, it has builds for x86, AMD64 and even ARM-based operating systems, meaning it should run on almost any device.

Installing qBittorrent as a Docker Container

Over the following sections, we will walk you through the entire process of installing qBittorrent to your system using a Docker container.

To run and manage qBittorrent, we will be utilizing a Docker Compose file. These files make managing services a breeze.

Installing Docker to your Device

1. Before we can run qBittorrent using Docker on your device, you will need to install Docker.

If you have Docker installed already, you can skip to the next section. Otherwise, run the following command.

curl -sSL https://get.docker.com | sh

2. After installing Docker, you will want to ensure your user is in the “docker” group.

You can add your user to this group by running the command below.

sudo usermod -aG docker $USER

3. Since we have changed your user’s group, you must restart your current session.

If you are using SSH to run these steps, you can log out using the command below.

logout

Alternatively, you can restart your system completely by running the command below.

sudo reboot

Setting up Folders for qBittorrent

4. Our next step is to create a folder to store the Docker Compose file for our qBittorrent container. It is also the directory where we will get the container to store its configuration files.

You can create a folder at “/opt/stacks/qbittorrent” by running the mkdir command in the terminal.

sudo mkdir -p /opt/stacks/qbittorrent

By using the “-p” option, the mkdir command will create all the directories within the given path.

5. The following steps will expect you to be in the directory we just created, so change into it by using the cd command.

cd /opt/stacks/qbittorrent

Writing a Docker Compose file for qBittorrent

6. We can now begin to write the Docker Compose file for qBittorrent. This Compose file is like instructions for how Docker should install and run qBittorrent.

To begin writing this file, use the following command within the terminal. We are using the nano text editor as it is one of the easiest editors to utilize.

sudo nano compose.yaml

7. In this file, you will want to type out the following lines. These lines configure the port that qBittorrent operates on, the timezone it should use, and more.

• <ACCEPTEULA>: qBittorrent requires you to agree to their EULA before you can use their client.
  
  If you accept these terms, replace this text with the word “accept“.
• <TIMEZONE>: The next thing you want to do is specify the time zone for qBittorrent to use when running within the container.
  
  You can find a valid value for this line by looking at Wikipedia’s list of tz database time zones. An example of a valid value here is “Australia/Hobart“.
• <DOWNLOADPATH>: Replace this value with the full path to where you want files downloaded to on your device.
  
  For example, if we wanted to store the files in our user’s home directory, we might use something like “/home/pimyubu/downloads“.

version: "3.9"

services:
  qbittorrent-nox:
    container_name: qbittorrent-nox
    environment:
      #- PGID=1000
      #- PUID=1000
      - QBT_EULA=<ACCEPTEULA>
      - QBT_VERSION=latest
      - QBT_WEBUI_PORT=8080
      - TZ=<TIMEZONE>
    image: qbittorrentofficial/qbittorrent-nox:latest
    ports:
      - 6881:6881/tcp
      - 6881:6881/udp
      - 8080:8080/tcp
    read_only: true
    stop_grace_period: 30m
    tmpfs:
      - /tmp
    tty: true
    volumes:
      - ./config:/config
      - <PATHTOSTOREDOWNLOADS>:/downloads

8. After typing out the lines above, you can save and quit by pressing CTRL + X, followed by Y, and then the ENTER key.

Starting your qBittorrent Container for the First Time

9. With the Compose file now written we can start the qBittorrent container using the following command in the terminal.

We don’t use the “-d” option here as we do not want Docker to detach from the terminal. This is because we need a password that qBittorrent generates at start-up.

docker compose up

10. After starting the qBittorrent container, you should see the following text appear within the terminal.

You should note the temporary password, as you will need this to access the web interface for the first time.

qbittorrent-nox  | WebUI will be started shortly after internal preparations. Please wait...
qbittorrent-nox  |
qbittorrent-nox  | ******** Information ********
qbittorrent-nox  | To control qBittorrent, access the WebUI at: http://localhost:8080
qbittorrent-nox  |
qbittorrent-nox  | The WebUI administrator username is: admin
qbittorrent-nox  | The WebUI administrator password was not set. A temporary password is provided for this session: MetBJdDbj

qbittorrent-nox  | You should set your own password in program preferences.

Accessing the qBittorrent Web Interface

11. To access the qBittorrent web interface, you must know the IP address of the machine Docker is running on.

If you are unsure of your IP, you can get it using the hostname command as shown below.

hostname -I

12. Once you know your IP address, go to the following web address in your favourite web browser.

Ensure you replace “<IPADDRESS>” with your IP.

http://<IPADDRESS>:8080

Setting the Admin Password for your qBittorrent Docker Container

13. With the qBittorrent web interface open in your web browser, you must type in your username and password (1.).

By default, the username will be “admin“, and the password will be the one generated and shown within the terminal earlier.

After typing out your username and password, click the “Login” button (2.).

14. After logging into qBittorrent, you must set a password; otherwise, your Docker container will generate a new password every time it starts.

To begin setting the password, click the cog icon in the taskbar.

15. With the settings page open, you will want to swap to the “Web UI” tab.

16. Once in the “Web UI” tab, scroll down until you see the “Authentication” header and type in a password you want to use to log in to the qBittorrent web interface.

17. After typing out a new password, scroll down until you see the “Save” button and click it.

This will save your new password to your qBittorrent Docker containers “config” volume.

Starting qBittorent in the Background

18. With a password set for your admin account, you can stop the container from running within your terminal.

To stop the container, press CTRL + C with the terminal open.

19. We can now start up the qBittorrent Docker again, but this time using the “-d” option.

This option detaches the container from the terminal once it starts up.

docker compose up -d

Updating the qBittorrent Docker Container

One advantage of running qBittorrent through a Docker container is that updating the software is as simple as running a few commands.

By the end of the following steps, you will be running the latest version.

1. To update our qBittorrent Docker container, we must change to the directory where we wrote the Compose file.

You can change this directory by using the following command within the terminal.

cd /opt/stacks/qbittorrent

2. Once we are in the correct directory, we can tell Docker to pull the latest version of the qBittorrent container.

docker compose pull

3. Even though we pulled a new version of the container, Docker will only begin to use it if we tell it to start again.

When starting the Compose stack, Docker will detect a new version of the qBittorrent container and move over to it.

docker compose up -d

Conclusion

Hopefully, at this point in the tutorial, you will now have qBittorrent running on your device using a Docker container.

Keeping the software in a container makes it significantly easier to update while keeping it somewhat separated from the rest of your system.

Please drop a comment below if you have encountered any issues with getting this torrent client running in a Docker container.

If you found this tutorial helpful, we highly recommend you check out our many other tutorials.

Weekly Updates Straight To Your Inbox

Receive our Raspberry Pi projects, coding tutorials, Linux guides and more!

Subscribe