Introduction
NOTE: for qBittorrent revisions older than 63ff5e3 (2020-09-19), use the legacy guide instead.
This how-to will guide you through compiling qBittorrent from source on Debian, Ubuntu, and other derivative distros.
Only follow this guide if you know what you are doing and this is what you really want. If you just want the latest version of qBittorrent, use our stable or unstable PPAs.
Install the dependencies
Boost and other miscellaneous build dependencies
You need to install these packages in order to be able to compile qBittorrent from source:
sudo apt install build-essential cmake git ninja-build pkg-config libboost-dev libssl-dev zlib1g-dev libgl1-mesa-dev
Qt libraries
qBittorrent uses the Qt framework as the basis for its GUI.
- qBittorrent 4.4.x requires at least Qt 5.15.2.
- At the time of writing, the current
masterbranch requires at least Qt 5.15.2.
Many distributions, in particular Debian, Ubuntu (especially LTS releases), and their derivatives don't provide up-to-date Qt packages in their repositories or are very slow in updating them. In such cases, you must get them from somewhere else, such as the official installer from the Qt website (unfortunately, this method requires the creation of an account, but you can just use a throwaway email), or a PPA you trust in the case of Ubuntu and other distributions that support that installation method.
For Debian and Ubuntu versions that include sufficiently up-to-date Qt packages, you can just install the following packages from the official repositories:
sudo apt install --no-install-recommends qtbase5-dev qttools5-dev libqt5svg5-dev
libtorrent
qBittorrent uses the libtorrent library by Arvid Norberg (aka libtorrent-rasterbar) as the backend.
It is possible to install the libtorrent development package directly from the distro's repositories:
sudo apt install libtorrent-rasterbar-dev
but the version may not be the most recent or exactly the one you want.
Alternatively, you can compile libtorrent yourself. qBittorrent 4.2.x and above requires the 1.2.x series(*).
qBittorrent 4.4.x requires minimum libtorrent 1.2.14 or 2.0.4.
git clone --recurse-submodules https://github.com/arvidn/libtorrent.git
cd libtorrent
git checkout RC_2_0 # or a 2.0.x tag
cmake -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_INSTALL_PREFIX=/usr/local
cmake --build build
sudo cmake --install build
The install step will install libtorrent to the chosen prefix (/usr/local, in this case), and generate an install_manifest.txt file in the build folder that can later be used to uninstall all installed files with sudo xargs rm < install_manifest.txt.
For more information on building and installing libtorrent (such as the available build configuration options), read the documentation.
(*)Technically, 4.2.x releases up to, and including, 4.2.5, actually support the 1.1.x libtorrent series as well, but it is just life support and not properly tested/developed.
Runtime-only dependencies
qBittorrent has a runtime-only dependency on Python 3 for its search engine functionality:
sudo apt install python3
Build qBittorrent
Download and extract a .tar archive from the GitHub releases page or clone the repository and checkout the branch/tag of your choice.
Then, configure and build with CMake:
cmake -G "Ninja" -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_INSTALL_PREFIX=/usr/local
cmake --build build
Check out the common information page to learn more about the available build configuration options (for compiling without the GUI, for instance) and CMake itself, if you're new to it.
Once qBittorrent is built, you can run it straight from the build directory. Documentation about running qBittorrent without GUI is available here.
Installing (optional)
To install qBittorrent to the prefix chosen at configure-time:
sudo cmake --install build
This will generate an install_manifest.txt file in the build folder that can later be used to uninstall all the installed files with sudo xargs rm < install_manifest.txt. To override the installation prefix at install-time, pass --prefix <install_prefix>.
Patches are welcome to implement Debian package generation with CPack.
General
- Installing qBittorrent
- Frequently Asked Questions (FAQ)
- qBittorrent options (current and deprecated)
- How to use qBittorrent as a tracker
- How to use portable mode
- Anonymous mode
- How to bind your vpn to prevent ip leaks
Troubleshooting
External programs
Search plugins
Themes
Translation
WebUI
WebUI API
| State | Version |
|---|---|
| Current | qBittorrent ≥ v4.1 |
| Previous | qBittorrent v3.2.0 - v4.0.x |
| Obsolete | qBittorrent < v3.2.0 |
WebAPI clients
Alternate WebUI
Reverse proxy setup for WebUI access
WebUI HTTPS configuration
- Let's Encrypt Certificates + Caddy2 Reverse Proxy
- Let's Encrypt certificates + NGINX reverse proxy - Linux
- Let's Encrypt certificates - Linux
- Self-signed SSL certificates - Linux
Linux
- Running qBittorrent without X server (WebUI only)
- Running qBittorrent without X server (WebUI only, systemd service set up, Ubuntu 15.04 or newer)
- OpenVPN and qBittorrent without X server
Development
- Coding style
- Contributing
- How to write a search plugin
- Using VSCode for qBittorrent development
- Setup GDB with Qt pretty printers
- How to debug WebUI code
Compilation
*BSD, Linux
- Alpine Linux
- CentOS 8.x
- Debian / Ubuntu and derivatives (CMake)
- Debian / Ubuntu and derivatives (autotools/qmake)
- Docker
- FreeBSD (no GUI)
- Fully static binaries on Linux (glibc or musl)
- Raspberry Pi OS / DietPi
- Raspbian for LeMaker Banana Pro