📘

qBittorrent

Please make yourself aware of the Ultra.cc Fair Usage Policy. Directly pointing any cloud storage directory using Rclone will create extreme strain on the disk and WILL cause a 24-hour ban on accessing your cloud storage repeatedly.

It is YOUR responsibility to ensure usage is within acceptable limits.

If you are on an HDD plan, you should be mindful not to have multiple simultaneous downloads active as it will cause high disk IO utilization, and negatively affect your disk neighbors. There is no set limit on how many active downloads you can have, though depending on the download speeds, we recommend 1-3 at the most. To monitor the disk IO utilization, see this link.

An advanced and multi-platform BitTorrent client with a nice Qt user interface as well as a Web UI for remote control and an integrated search engine. qBittorrent aims to meet the needs of most users while using as little CPU and memory as possible.

Default File Paths

Default Downloads Folder: ~/downloads/qbittorrent
Configuration Folder: ~/.config/qbittorrent
Watch Folder: ~/watch/qbittorrent

Add `.torrent` File

To add a .torrent file to qBittorrent via the Web UI you have two options, either click File in the top menu bar, then click Add torrent file or click the small white page icon. This will open your file explorer for you to add your .torrent file.

Add Magnet Link

Adding a magnet link is the same. However, instead of adding a torrent file, you choose Add torrent link and paste your links in the dialog box. You can paste multiple links at once.

Find IP Address

If your private tracker requests the IP of your torrent client, you can find it with the following instructions. qBittorrent will use a pooled IP for improved performance. You can see which IP is being used by qBittorrent from the Apps tab of your User Control Panel. Find qBittorrent in the list and press the Show Info button to reveal the Assigned IP: xxx.xxx.xxx.xxx

Configuration

Install Dark Theme (Optional)

Dark Theme is not official, please keep this in mind if you encounter any artifacts or misplaced elements in your Web UI.

The below instructions will by script install a dark theme to your qBittorrent instance. Should you rather want to install Theme Park manually, you can follow our guide 📘Theme Park.

Check out the dark themes at Theme Park.
Connect to your Ultra service via SSH.
Run the script via the following SSH command:

bash <(wget -qO- https://scripts.ultra.cc/main/qBittorrent/qBitTheme.sh)

Select one theme out of the four dark themes available from Theme Park.

Organizr Dark, Dark, Darcula or Overseerr.
If you get a Webserver error, please restart your webserver from the Overview tab on the UCP.

Enable Public Torrent Seeding (Optional)

Public torrents are stopped after download by default to avoid HDD IO resource abuse and inadvertent usage of upload traffic. You can easily enable public torrent seeding with the instructions given below.
Connect to your Ultra service via SSH.
Execute the following command:

app-qbittorrent restart --remove-pubscript

To enable the script again, execute the following command:

app-qbittorrent restart --add-pubscript

Note that changing the password, repairing or reinstalling the torrent client will disable public torrent seeding again.

Enable Automatic Extraction of RAR archives (Optional)

If a torrent's data is archived within .rar(s) then you can enable the following setting to allow qBittorrent to run a command to automatically extract the data within the torrent's download directory after the torrent download has completed.

Navigate to your qBittorrent's settings
Within the Downloads tab, scroll down to find the Run external program on torrent completion text box and enter the following command:

qBittorrent version equal to or lower than 4.3.9

/usr/bin/7z x "%F/*.rar" -o "%F/"

qBittorrent version equal to or higher than 4.5.5

/usr/bin/unrar e %F/*.rar -o %F/

Click the Save button to save your changes then wait for your qBittorrent web interface to reload.

Note that setting this automatic extraction command on completion will only apply to torrents finished after the command is saved. Finished torrents with the .rar archives that completed before setting this automatic extraction method will still need to be extracted manually.

Torrent Queue and Download Limits

If you have an Ultra service with HDD instead of NVME, you need to be mindful of your disk neighbors and not hammer the disk with high IO utilization. See this guide for more information on how to check your disk IO utilization.

One way to mitigate this is to limit the amount of active downloads and total active torrents in your torrent client. Below you will find instructions on how to do this for qBittorrent.

In the qBittorrent WebUI, click on cog icon in the top menu bar to open settings.
Click on the BitTorrent at the top.
Set Maximum active downloads to 3 at most. Keeping this at 3 or lower prevents excessive disk IO, which would slow down your slot and negatively affect other users sharing the same disk. Multiple simultaneous downloads each generate their own read/write operations, and this adds up quickly on HDD plans.
Set Maximum active uploads (Seeding) to a reasonable starting value such as 200 and increase gradually if your slot handles it well. Do not jump straight to a high number.
Set Maximum active torrents (Total) to a reasonable starting value such as 500 and increase gradually as needed.

qBittorrent can handle up to approximately 10,000 torrents before it becomes unstable. However, you should not set your limits to 10,000 right away. Start with a lower value and gradually increase it while monitoring your slot's performance. Setting the limit too high from the start can cause excessive memory usage, slow WebUI response times, and even crashes.

Upgrade qBittorrent

Please note, downgrading of qBittorrent can be a bit buggy, and it should be avoided.

In this section, we will show you how to successfully upgrade your qBittorrent instance from 4.3.9 to 4.5.5, 4.6.3 or 5.0.x. Before proceeding with the upgrade, we recommend taking a backup of your qBittorrent config directory and torrent session state.

First, stop qBittorrent from the Apps tab on the UCP.
Connect to your Ultra.cc service via SSH. Once connected, take a backup of your qBittorrent config and torrent session by executing the following command:

cp -r ~/.config/qBittorrent ~/.config/qBittorrent.bak && cp -r ~/.local/share/qBittorrent ~/.local/share/qBittorrent.bak

Next, go back to the UCP and uninstall qBittorrent. Make sure to let at least one minute pass after qBittorrent has been uninstalled.
Then, while still on the UCP, go to the Installers tab and re-install qBittorrent while choosing version a new version.

DO NOT click the Cleanup button, as that will wipe your qBittorrent config directory and torrent session state. Even though we have previously backed it up, we want to avoid doing this.

Once the installation has been completed, you can proceed with accessing the qBittorrent Web UI. If successful, your qBittorrent configuration and torrent session state will be preserved.

Restore Backup

If the qBittorrent configuration and torrent session state was not successfully preserved after the upgrade. It can be manually restored from the backup that was made pre-upgrade.

First, stop qBittorrent from the Apps tab on the UCP.
Connect to your Ultra.cc service via SSH, and execute the following command:

rm -rf ~/.config/qBittorrent && rm -rf ~/.local/share/qBittorrent && cp -r ~/.config/qBittorrent.bak ~/.config/qBittorrent && cp -r ~/.local/share/qBittorrent.bak ~/.local/share/qBittorrent

Next, restart qBittorrent by executing app-qbittorrent restart, or go back to the UCP and restart qBittorrent from the Apps tab.
Access your qBittorrent Web UI to confirm the backup restoration was successful.

Troubleshooting Information

Torrents Not Connecting

If your torrents are stuck and not connecting to any peers, try the following:

Repair qBittorrent: Go to the Apps tab on the UCP, find qBittorrent and click the Repair button. This will repair any broken configuration without affecting your torrents.

WebUI Not Starting with 502 Error

If qBittorrent's Web UI is showing a 502 error, follow these steps in order:

Restart the app and Webserver

The most common fix for 502 errors is to simply restart or repair the app, or restart the webserver. The 502 error page will usually tell you where the problem is and what needs to be restarted.

Go to the Apps tab on the UCP and restart qBittorrent.
If that does not work, try restarting or reinstalling the webserver from the Overview tab on the UCP.
You may also need to repair qBittorrent after a webserver restart to fully fix the issue.

If the above does not resolve the issue, connect to your service via SSH and run the following commands:

app-nginx uninstall

app-nginx install

app-qbittorrent repair

app-qbittorrent restart

Check your disk’s IO

High disk IO can cause 502 or timeout issues. See our SSH Troubleshooting Information guide to check if high IO is the cause. If the disk IO is high and you suspect that your activities are not the cause, please open a support ticket so we can investigate.

Backup and reinstall

If the above steps did not resolve the issue, you should back up your qBittorrent configuration and torrent session, then reinstall the application.

It is critical that you back up your torrent session before reinstalling. If you skip this step, all of your torrents will be disconnected from the app and you will lose your seeding state.

Connect to your service via SSH.
First, create an application backup:

app-qbittorrent backup

Next, back up your torrent session separately:

cp -r ~/.local/share/qBittorrent ~/.local/share/qbit-backup

cp -r ~/.local/share/qBittorrent/BT_backup/ ~/.local/share/qBittorrent/BT_backup-bak/

Once the backups are complete, go to the UCP and uninstall qBittorrent, then reinstall it using the same version that was previously installed.
If the WebUI starts after reinstalling, check that your configuration and torrents are intact. If they are missing, you can restore them by following our Restore Application Backup guide.

Constant Crashes

qBittorrent can become unstable when managing a large number of torrents. While the theoretical limit is around 10,000 torrents, instability can occur well before reaching that number depending on your slot's resources and disk type.

If you are experiencing frequent crashes:

Reduce the Maximum active torrents (Total) in your qBittorrent settings. Start with a lower value (e.g., 500) and increase gradually.
Reduce the Maximum active downloads to 3 or fewer.
Consider removing old or unnecessary torrents to keep the total count manageable.
Monitor your slot's resource usage via SSH to see if memory or IO is a contributing factor.

Slow Torrents

If your torrents are downloading slowly, try the following:

Test with a well-seeded torrent: Download a popular Linux ISO such as the latest Linux Mint or Ubuntu release. These are widely seeded and will help determine if the issue is on the service’s end or related to the torrent swarm. If the test torrent downloads at full speed, the slow speeds on your other torrents are caused by a poorly seeded swarm, and there is nothing that can be done on our side.
Check disk IO: High disk IO utilization can throttle download speeds. See our SSH Troubleshooting Information guide to check if this is the cause. If the disk IO is high and you suspect that your activities are not the cause, please open a support ticket so we can investigate.

Slow WebUI

If the qBittorrent Web UI is responding slowly or taking a long time to load:

Check disk IO: A saturated disk will slow down everything, including the WebUI. See our SSH Troubleshooting Information guide to verify. If the disk IO is high and you suspect that your activities are not the cause, please open a support ticket so we can investigate.
Reduce active torrent count: A very high number of active torrents puts additional load on the WebUI. Lower your Maximum active torrents (Total) to improve responsiveness.

If you require further assistance, you can open a support ticket here!

Feedback and suggestions regarding this article are welcome on our Discord server

qBittorrent
Default File Paths
Add .torrent File
Add Magnet Link
Find IP Address
Configuration
Install Dark Theme (Optional)
Enable Public Torrent Seeding (Optional)
Enable Automatic Extraction of RAR archives (Optional)
Torrent Queue and Download Limits
Upgrade qBittorrent
Restore Backup
Troubleshooting Information
Torrents Not Connecting
WebUI Not Starting with 502 Error
Constant Crashes
Slow Torrents
Slow WebUI

📘

qBittorrent

Default File Paths

Default Downloads Folder: ~/downloads/qbittorrent
Configuration Folder: ~/.config/qbittorrent
Watch Folder: ~/watch/qbittorrent

Add `.torrent` File

Add Magnet Link

Adding a magnet link is the same. However, instead of adding a torrent file, you choose Add torrent link and paste your links in the dialog box. You can paste multiple links at once.

Find IP Address

Configuration

Install Dark Theme (Optional)

Dark Theme is not official, please keep this in mind if you encounter any artifacts or misplaced elements in your Web UI.

The below instructions will by script install a dark theme to your qBittorrent instance. Should you rather want to install Theme Park manually, you can follow our guide 📘Theme Park.

Check out the dark themes at Theme Park.
Connect to your Ultra service via SSH.
Run the script via the following SSH command:

bash <(wget -qO- https://scripts.ultra.cc/main/qBittorrent/qBitTheme.sh)

Select one theme out of the four dark themes available from Theme Park.

Organizr Dark, Dark, Darcula or Overseerr.
If you get a Webserver error, please restart your webserver from the Overview tab on the UCP.

Enable Public Torrent Seeding (Optional)

Public torrents are stopped after download by default to avoid HDD IO resource abuse and inadvertent usage of upload traffic. You can easily enable public torrent seeding with the instructions given below.
Connect to your Ultra service via SSH.
Execute the following command:

app-qbittorrent restart --remove-pubscript

To enable the script again, execute the following command:

app-qbittorrent restart --add-pubscript

Note that changing the password, repairing or reinstalling the torrent client will disable public torrent seeding again.

Enable Automatic Extraction of RAR archives (Optional)

Navigate to your qBittorrent's settings
Within the Downloads tab, scroll down to find the Run external program on torrent completion text box and enter the following command:

qBittorrent version equal to or lower than 4.3.9

/usr/bin/7z x "%F/*.rar" -o "%F/"

qBittorrent version equal to or higher than 4.5.5

/usr/bin/unrar e %F/*.rar -o %F/

Click the Save button to save your changes then wait for your qBittorrent web interface to reload.

Torrent Queue and Download Limits

One way to mitigate this is to limit the amount of active downloads and total active torrents in your torrent client. Below you will find instructions on how to do this for qBittorrent.

In the qBittorrent WebUI, click on cog icon in the top menu bar to open settings.
Click on the BitTorrent at the top.
Set Maximum active downloads to 3 at most. Keeping this at 3 or lower prevents excessive disk IO, which would slow down your slot and negatively affect other users sharing the same disk. Multiple simultaneous downloads each generate their own read/write operations, and this adds up quickly on HDD plans.
Set Maximum active uploads (Seeding) to a reasonable starting value such as 200 and increase gradually if your slot handles it well. Do not jump straight to a high number.
Set Maximum active torrents (Total) to a reasonable starting value such as 500 and increase gradually as needed.

Upgrade qBittorrent

Please note, downgrading of qBittorrent can be a bit buggy, and it should be avoided.

First, stop qBittorrent from the Apps tab on the UCP.
Connect to your Ultra.cc service via SSH. Once connected, take a backup of your qBittorrent config and torrent session by executing the following command:

cp -r ~/.config/qBittorrent ~/.config/qBittorrent.bak && cp -r ~/.local/share/qBittorrent ~/.local/share/qBittorrent.bak

Next, go back to the UCP and uninstall qBittorrent. Make sure to let at least one minute pass after qBittorrent has been uninstalled.
Then, while still on the UCP, go to the Installers tab and re-install qBittorrent while choosing version a new version.

DO NOT click the Cleanup button, as that will wipe your qBittorrent config directory and torrent session state. Even though we have previously backed it up, we want to avoid doing this.

Once the installation has been completed, you can proceed with accessing the qBittorrent Web UI. If successful, your qBittorrent configuration and torrent session state will be preserved.

Restore Backup

If the qBittorrent configuration and torrent session state was not successfully preserved after the upgrade. It can be manually restored from the backup that was made pre-upgrade.

First, stop qBittorrent from the Apps tab on the UCP.
Connect to your Ultra.cc service via SSH, and execute the following command:

rm -rf ~/.config/qBittorrent && rm -rf ~/.local/share/qBittorrent && cp -r ~/.config/qBittorrent.bak ~/.config/qBittorrent && cp -r ~/.local/share/qBittorrent.bak ~/.local/share/qBittorrent

Next, restart qBittorrent by executing app-qbittorrent restart, or go back to the UCP and restart qBittorrent from the Apps tab.
Access your qBittorrent Web UI to confirm the backup restoration was successful.

Troubleshooting Information

Torrents Not Connecting

If your torrents are stuck and not connecting to any peers, try the following:

Repair qBittorrent: Go to the Apps tab on the UCP, find qBittorrent and click the Repair button. This will repair any broken configuration without affecting your torrents.

WebUI Not Starting with 502 Error

If qBittorrent's Web UI is showing a 502 error, follow these steps in order:

Restart the app and Webserver

The most common fix for 502 errors is to simply restart or repair the app, or restart the webserver. The 502 error page will usually tell you where the problem is and what needs to be restarted.

Go to the Apps tab on the UCP and restart qBittorrent.
If that does not work, try restarting or reinstalling the webserver from the Overview tab on the UCP.
You may also need to repair qBittorrent after a webserver restart to fully fix the issue.

If the above does not resolve the issue, connect to your service via SSH and run the following commands:

app-nginx uninstall

app-nginx install

app-qbittorrent repair

app-qbittorrent restart

Check your disk’s IO

Backup and reinstall

If the above steps did not resolve the issue, you should back up your qBittorrent configuration and torrent session, then reinstall the application.

It is critical that you back up your torrent session before reinstalling. If you skip this step, all of your torrents will be disconnected from the app and you will lose your seeding state.

Connect to your service via SSH.
First, create an application backup:

app-qbittorrent backup

Next, back up your torrent session separately:

cp -r ~/.local/share/qBittorrent ~/.local/share/qbit-backup

cp -r ~/.local/share/qBittorrent/BT_backup/ ~/.local/share/qBittorrent/BT_backup-bak/

Once the backups are complete, go to the UCP and uninstall qBittorrent, then reinstall it using the same version that was previously installed.
If the WebUI starts after reinstalling, check that your configuration and torrents are intact. If they are missing, you can restore them by following our Restore Application Backup guide.

Constant Crashes

If you are experiencing frequent crashes:

Reduce the Maximum active torrents (Total) in your qBittorrent settings. Start with a lower value (e.g., 500) and increase gradually.
Reduce the Maximum active downloads to 3 or fewer.
Consider removing old or unnecessary torrents to keep the total count manageable.
Monitor your slot's resource usage via SSH to see if memory or IO is a contributing factor.

Slow Torrents

If your torrents are downloading slowly, try the following:

Test with a well-seeded torrent: Download a popular Linux ISO such as the latest Linux Mint or Ubuntu release. These are widely seeded and will help determine if the issue is on the service’s end or related to the torrent swarm. If the test torrent downloads at full speed, the slow speeds on your other torrents are caused by a poorly seeded swarm, and there is nothing that can be done on our side.
Check disk IO: High disk IO utilization can throttle download speeds. See our SSH Troubleshooting Information guide to check if this is the cause. If the disk IO is high and you suspect that your activities are not the cause, please open a support ticket so we can investigate.

Slow WebUI

If the qBittorrent Web UI is responding slowly or taking a long time to load:

Check disk IO: A saturated disk will slow down everything, including the WebUI. See our SSH Troubleshooting Information guide to verify. If the disk IO is high and you suspect that your activities are not the cause, please open a support ticket so we can investigate.
Reduce active torrent count: A very high number of active torrents puts additional load on the WebUI. Lower your Maximum active torrents (Total) to improve responsiveness.

If you require further assistance, you can open a support ticket here!

Feedback and suggestions regarding this article are welcome on our Discord server

qBittorrent
Default File Paths
Add .torrent File
Add Magnet Link
Find IP Address
Configuration
Install Dark Theme (Optional)
Enable Public Torrent Seeding (Optional)
Enable Automatic Extraction of RAR archives (Optional)
Torrent Queue and Download Limits
Upgrade qBittorrent
Restore Backup
Troubleshooting Information
Torrents Not Connecting
WebUI Not Starting with 502 Error
Constant Crashes
Slow Torrents
Slow WebUI

qBittorrent

qBittorrent

Default File Paths

Add .torrent File

Add Magnet Link

Find IP Address

Configuration

Install Dark Theme (Optional)

Enable Public Torrent Seeding (Optional)

Enable Automatic Extraction of RAR archives (Optional)

Torrent Queue and Download Limits

Upgrade qBittorrent

Restore Backup

Troubleshooting Information

Torrents Not Connecting

WebUI Not Starting with 502 Error

Constant Crashes

Slow Torrents

Slow WebUI

qBittorrent

qBittorrent

Default File Paths

Add .torrent File

Add Magnet Link

Find IP Address

Configuration

Install Dark Theme (Optional)

Enable Public Torrent Seeding (Optional)

Enable Automatic Extraction of RAR archives (Optional)

Torrent Queue and Download Limits

Upgrade qBittorrent

Restore Backup

Troubleshooting Information

Torrents Not Connecting

WebUI Not Starting with 502 Error

Constant Crashes

Slow Torrents

Slow WebUI

Add `.torrent` File

Add `.torrent` File