Install qBittorrent VPN (qBittorrent behind Gluetun)
qBittorrent VPN is qBittorrent that runs behind Gluetun, a VPN client. All of its traffic goes through your VPN. This page takes you from a fresh server to a working install, and shows you how to prove the traffic uses the VPN.
Before you start
Section titled “Before you start”- You have finished Prerequisites. See the Quick start.
- You have a Basic, Plus or Pro license. See Licenses.
- You have a VPN account that gives you a WireGuard or OpenVPN setup. You need the provider name. For WireGuard, you also need the private key and the address. For OpenVPN, you need the username and password.
- Your server has a
/dev/net/tundevice. Step 1 checks this.
1. Set the network adapter
Section titled “1. Set the network adapter”Gluetun can’t be installed until Deployrr has checked your server for the VPN network adapter. Tailscale, ZeroTier and Cloudflare Tunnel need this step too.
-
Go to System > Network.
-
Read the Network Adapter box and select OK. It says the adapter is needed for VPN apps, such as torrent clients, and is normally at
/dev/net/tun. -
Watch the result. A good result looks like this:
Network adapter device found at /dev/net/tunDevice is readable and writable by YOUR_USERNetwork adapter detection completed - VPN support enabled -
Go back to the System Preparation menu. The line now reads Network Adapter (for VPN) - /dev/net/tun.
If the menu line still reads Not Set/Found, see If the adapter is not found.
2. Install the apps qBittorrent VPN needs
Section titled “2. Install the apps qBittorrent VPN needs”qBittorrent VPN won’t install unless Gluetun and DeUnhealth are running. DeUnhealth restarts a container when it turns unhealthy. It needs Socket Proxy to be running first.
-
Go to Docker > Socket Proxy and install it if it isn’t running. See Socket Proxy.
-
Go to Apps > Browse Apps, select DeUnhealth and choose Install. It asks no questions.
-
Select Gluetun and choose Install.
-
At each prompt, enter the value from your VPN provider:
Prompt What to enter Enter value for GLUETUN_VPN_SERVICE_PROVIDER:Your provider’s name exactly as Gluetun expects it, for example surfshark,nordvpnormullvad. Deployrr doesn’t check it.Enter value for GLUETUN_VPN_TYPE:wireguard(the default) oropenvpn, in lowercase. Any other value, such asWireGuard, givesUnknown VPN typeand Deployrr asks for no VPN details. -
Next you see one Docker Environment Variables box after another. For
wireguardthey ask for the Private Key and the Wireguard Addresses from your provider’s configuration. The address usually looks likeXX.XX.XX.XX/XX. Foropenvpnthey ask for the OpenVPN Username and OpenVPN Password. What you type is shown on screen, so make sure nobody is watching. Don’t cancel these boxes: Deployrr goes on anyway, and Gluetun can’t connect without the values. -
Wait up to 60 seconds. Deployrr waits for Gluetun to connect to the VPN. Look for this:
VPN connected successfully!Public IP: ...Note the public IP. You use it later.
If you see Timed out after 60s. Could not verify VPN connection., Gluetun did not connect. Read its log:
sudo docker logs gluetunWith the Deployrr bash aliases: dlogs gluetun. It keeps following the log; press Ctrl+C to stop.
At the end, Deployrr shows a Gluetun - Installation Notes box. It says you can route other containers through Gluetun by adding network_mode: service:gluetun to their compose configuration. You don’t need that for qBittorrent VPN. Its install does it for you. To do it for an app of your own, see Route another app through Gluetun. To keep the VPN in one country, see Choose a VPN country or server.
3. Set your Downloads Folder
Section titled “3. Set your Downloads Folder”qBittorrent VPN saves its files in your Downloads Folder. If it isn’t set, the install shows Downloads Folder - Must be set (System > Folders menu). Set it in System > Folders. See Set your media, downloads and other folders.
The install creates a torrents folder inside your Downloads Folder. It has the subfolders movies, tv, others and indexes.
4. Install qBittorrent VPN
Section titled “4. Install qBittorrent VPN”- Go to Apps > Browse Apps.
- Select qBittorrent VPN and choose Install.
- Read the qBittorrent VPN Setup box. It says Gluetun must be running and connected to your VPN, and that you reach the web page through Gluetun’s port. Select OK. Deployrr checks the requirements after this box.
- At Port Configuration, enter the port for the web page. The default is
8082. Deployrr suggests the first free port from there. If the port is taken, see Port is already in use. - Wait for the four steps to finish: configuring the Gluetun port, stopping qBittorrent VPN, restarting Gluetun and starting qBittorrent VPN. The last step can show an error and leave qBittorrent VPN stopped, so check it after every install: run
sudo docker ps -a(ordps). Ifqbittorrent-vpnisn’t listed asUp, recreate it: Tools > Stack Manager > Recreate and pickqbittorrent-vpn, ordcrec qbittorrent-vpnwith the aliases. - Read the qBittorrent VPN - Installation Notes box at the end. It has two notes. One is about the login; log in as in Open qBittorrent and change the login. The other is about connecting Arr apps; use the host and port in Connect your Arr apps.
If you see Required app not running with gluetun must be installed and running first or deunhealth must be installed and running first, go back to step 2. Deployrr only checks that the container is running, not that the VPN is connected. Installing DeUnhealth without Socket Proxy shows socket-proxy must be installed and running first. See also Requirements Not Met.
5. Open qBittorrent and change the login
Section titled “5. Open qBittorrent and change the login”-
Open this address. Replace
YOUR_SERVER_IPwith your server’s local IP address andPORTwith the port you chose in step 4:http://YOUR_SERVER_IP:PORT -
Log in with the username
adminand the temporary password qBittorrent prints in its log. This command shows only the lines that mention a password:Terminal window sudo docker logs qbittorrent-vpn 2>&1 | grep -i passwordUse the last one. qBittorrent prints a new temporary password every time it starts until you set your own. The
dlogs qbittorrent-vpnalias shows only the last 50 lines, so the password line may already be gone from it. -
In qBittorrent, go to Tools > Options > WebUI and set a new password.
-
Go to Tools > Options > Downloads. qBittorrent VPN starts with
/downloads/as its Default Save Path. Change it to/data/downloads/torrents/others/, and the incomplete folder, if you use one, to/data/downloads/torrents/incomplete/. Only paths under/data/downloadsreach your Downloads Folder and the Arr apps. Select Save.
qBittorrent VPN is not behind Traefik. You can’t give it a subdomain or a login from Traefik. Always use the address above. If the page doesn’t open, see qBittorrent web UI says Unauthorized or won’t open.
6. Connect your Arr apps
Section titled “6. Connect your Arr apps”In Sonarr, Radarr and other apps, add qBittorrent as a download client with these values:
- Host:
gluetun - Port:
8080
The host is gluetun because qBittorrent VPN shares Gluetun’s network. It has no network or container address of its own. See Connect your apps to each other.
To see the same idea in a manual setup, watch Gluetun VPN kill switch guide: connect Radarr to qBittorrent at 28:19 (manual Docker Compose setup; it also puts qBittorrent behind Traefik, which Deployrr v6 does not).
Check it worked
Section titled “Check it worked”Check that qBittorrent VPN uses your VPN address, not your home address.
-
Find your home IP address. Run this on the server (install
curlfirst if it’s missing):Terminal window curl -s https://ifconfig.me -
Find the IP address that qBittorrent VPN sees. Run this command inside its container:
Terminal window sudo docker exec qbittorrent-vpn curl -s https://ifconfig.meWith the Deployrr bash aliases:
dexec qbittorrent-vpn curl -s https://ifconfig.me. -
Compare the two addresses. They must be different.
-
Compare the second address with the
Public IPGluetun showed at install. You can also find it in the Gluetun log, in the linePublic IP address is. They should match.
If both commands print the same address, qBittorrent VPN is not using the VPN. Stop torrenting and check Gluetun with sudo docker logs gluetun (or dlogs gluetun).
You can also run sudo docker ps (or dps). Both gluetun and qbittorrent-vpn must show as Up.
If Gluetun doesn’t connect
Section titled “If Gluetun doesn’t connect”Gluetun connects only when the provider name and your key, address, username or password match what your VPN provider gave you. Read its log first to see what failed:
sudo docker logs gluetunThen fix the values in one of two ways. Editing .env keeps everything else as it is. Reinstalling Gluetun asks every question again, but undoes part of the qBittorrent VPN install.
Deployrr saves your answers in the .env file in your Docker folder:
.env line |
What it holds |
|---|---|
GLUETUN_VPN_SERVICE_PROVIDER |
Your provider’s name, such as mullvad |
GLUETUN_VPN_TYPE |
wireguard or openvpn |
GLUETUN_WIREGUARD_PRIVATE_KEY |
WireGuard private key |
GLUETUN_WIREGUARD_ADDRESSES |
WireGuard address |
GLUETUN_OPENVPN_USERNAME |
OpenVPN username |
GLUETUN_OPENVPN_PASSWORD |
OpenVPN password |
Fix the values in .env
Section titled “Fix the values in .env”Use this when the provider name or a key, address or password was wrong. Your qBittorrent VPN setup stays as it is.
-
Back up
.env. ReplaceYOUR_DOCKER_FOLDERwith your Docker folder path:Terminal window sudo cp YOUR_DOCKER_FOLDER/.env YOUR_DOCKER_FOLDER/.env.bak -
Open
.envwith Tools > .env Editor (Pro), or by hand:Terminal window sudo nano YOUR_DOCKER_FOLDER/.env -
Correct the lines from the table. Keep each value in single quotes, as Deployrr writes them, for example
GLUETUN_WIREGUARD_PRIVATE_KEY='YOUR_KEY'. If a line is missing (for example because you cancelled a box during the install), add it. See Edit .env values and secrets. -
Recreate Gluetun: Tools > Stack Manager > Recreate and pick
gluetun. With the aliases:dcrec gluetun. -
Check that it connected. This prints a line when it did:
Terminal window sudo docker logs gluetun 2>&1 | grep "Public IP address is" -
Recreate qBittorrent VPN the same way (
dcrec qbittorrent-vpn). It uses Gluetun’s network, so it must be built again after Gluetun is. Recreate keeps its settings and your login.
Don’t switch GLUETUN_VPN_TYPE between wireguard and openvpn here. Gluetun’s compose file only has the lines for the type you chose at install switched on. To change the type, reinstall Gluetun.
Reinstall Gluetun
Section titled “Reinstall Gluetun”Use this to change the VPN type or to start over.
- Go to Apps > Browse Apps, select Gluetun and choose Install. At the Already Installed prompt, choose Yes.
- Answer every prompt again, as in step 2. The provider box starts empty and the type box starts at
wireguard, so type your own values. The key, address, username and password boxes may show your old values. Replace them if they were wrong. - Wait for
VPN connected successfully!.
The reinstall replaces Gluetun’s compose file with a fresh one, and removes the old Gluetun container. qBittorrent VPN’s web page port is switched off again, and qBittorrent VPN loses its network. Fix both:
-
Back up and open the Gluetun file.
HOSTNAMEis your server’s hostname:Terminal window sudo cp YOUR_DOCKER_FOLDER/compose/HOSTNAME/gluetun.yml YOUR_DOCKER_FOLDER/compose/HOSTNAME/gluetun.yml.baksudo nano YOUR_DOCKER_FOLDER/compose/HOSTNAME/gluetun.yml -
Remove the
#and the space after it in front of these two lines. Leave the other#lines alone:ports:- $QBITTORRENTVPN_PORT:8080 -
Recreate
gluetun, thenqbittorrent-vpn, as in steps 4 to 6 above.
Installing qBittorrent VPN again also does all of this, but it resets your qBittorrent login and settings. See qBittorrent web UI says Unauthorized or won’t open.
Choose a VPN country or server
Section titled “Choose a VPN country or server”Deployrr doesn’t ask where your VPN should connect, so Gluetun picks a server from your provider’s list. To keep it in one country or city, add a filter to Gluetun’s compose file. You might want this for speed, or because your provider offers port forwarding only on some servers.
-
Open your provider’s page in the Gluetun wiki and note the filter lines it supports. Not every provider has every filter. Private Internet Access, for example, has
SERVER_REGIONSbut notSERVER_COUNTRIES. -
List the names Gluetun knows for your provider. Replace
mullvadwith your provider’s name as you typed it at install (if the name has spaces, use hyphens instead), andYOUR_DOCKER_FOLDERwith your Docker folder path:Terminal window sudo docker run --rm -v YOUR_DOCKER_FOLDER/appdata/gluetun:/gluetun qmcgaw/gluetun format-servers -mullvadIt prints a table of your provider’s servers, for example with the columns Country, City and Hostname. Some providers show other columns, such as Region. Copy the names exactly as they appear.
-
Back up and open
gluetun.ymlas in Reinstall Gluetun. -
Under
environment:, add one of the lines your provider supports. Match the indent of theVPN_TYPE:line in your file, and leave the other lines as they are. Separate more than one name with commas:environment:TZ: $TZVPN_SERVICE_PROVIDER: $GLUETUN_VPN_SERVICE_PROVIDERVPN_TYPE: $GLUETUN_VPN_TYPESERVER_COUNTRIES: Netherlands,SwedenLine Picks servers by SERVER_COUNTRIES:Country SERVER_REGIONS:Region SERVER_CITIES:City SERVER_HOSTNAMES:One exact server. This is the narrowest choice: if that server leaves Gluetun’s list, Gluetun can’t connect. Use one line to start with. Each filter you add narrows the list further.
-
Recreate Gluetun and check that it connected, as in steps 4 and 5 of Fix the values in .env. If you installed qBittorrent VPN, recreate it too (step 6).
-
Run the checks in Check it worked. The
Public IP address isline in the Gluetun log usually shows the country too.
If Gluetun doesn’t connect after the change, the names may not match your provider’s list, or your provider may not support that filter. Remove the line, recreate Gluetun and check the log.
Some providers tie a WireGuard key to one server. With those, a filter can pick a server your key doesn’t work on. Check your provider’s page in the Gluetun wiki and your provider’s own help before you narrow the list.
Installing qBittorrent VPN again keeps your line, because it only edits the port lines in gluetun.yml. Reinstalling Gluetun replaces the file, so add the line again after that.
For more Gluetun settings in a manual setup, see the Gluetun Docker guide. The qBittorrent VPN Setup box links to it too.
Route another app through Gluetun
Section titled “Route another app through Gluetun”You can send a second app’s traffic through the VPN the same way qBittorrent VPN does. Do this for your own services in custom.yml. Don’t edit the compose file of an app Deployrr installed: a reinstall replaces it. Sonarr, Radarr and the other Arr apps don’t need the VPN; the comment at the top of gluetun.yml says so too.
The app then shares Gluetun’s network. It has no network, ports or container address of its own, and it loses its connection whenever Gluetun stops or is recreated.
-
In your service in
custom.yml, add thenetwork_modeline and remove the service’sports:andnetworks:sections. Docker Compose refuses to start a service that has them together withnetwork_mode:services:myapp:image: SOME_IMAGEcontainer_name: myappnetwork_mode: "service:gluetun" -
Back up and open
gluetun.ymlas in Reinstall Gluetun. Underports:, add a line for your app’s web port,HOST_PORT:CONTAINER_PORT. Ifports:still starts with#(qBittorrent VPN isn’t installed), remove the#in front of it. Leave the qBittorrent VPN line as it is:ports:- $QBITTORRENTVPN_PORT:8080- 8090:9000All apps behind Gluetun share one network, so two of them can’t listen on the same port inside. qBittorrent VPN already uses
8080. Check that the host port is free; see Port is already in use. -
Recreate Gluetun (
dcrec gluetun), then start your app withdcup myapp(dcrec myappif it already runs), then recreate qBittorrent VPN (dcrec qbittorrent-vpn) if you have it. These are Deployrr bash aliases. -
Open the app at
http://YOUR_SERVER_IP:HOST_PORT. Other apps connect to it with the hostgluetunand the container port, for examplegluetun:9000. -
Check the address it uses, as in Check it worked:
sudo docker exec myapp curl -s https://ifconfig.me. Some images don’t includecurl.
Reinstalling Gluetun replaces gluetun.yml, so add your port line again after that.
Use Gluetun’s HTTP proxy
Section titled “Use Gluetun’s HTTP proxy”Gluetun has a built-in HTTP proxy. Point a browser or another device on your home network at it, and that traffic leaves through the VPN too, without a VPN app on the device. Deployrr leaves it off. Its port line is already in gluetun.yml, commented out.
Anyone who can reach the port can use your VPN. Set a username and password, and don’t forward the proxy port on your router. If your server has a public IP address, such as a VPS, don’t open the port at all: a published Docker port gets past firewalls such as UFW.
-
Back up and open
gluetun.ymlas in Reinstall Gluetun. -
Under
environment:, add these lines at the indent of theVPN_TYPE:line. Pick your own username and password:HTTPPROXY: "on"HTTPPROXY_USER: YOUR_PROXY_USERHTTPPROXY_PASSWORD: YOUR_PROXY_PASSWORD -
Under
ports:, remove the#in front of the8888:8888/tcpline. Ifports:still starts with#(qBittorrent VPN isn’t installed), remove the#in front of it too:ports:- $QBITTORRENTVPN_PORT:8080 # qBittorrent available at http://DOCKER-HOST-IP:$QBITTORRENTVPN_PORT- 8888:8888/tcp # HTTP proxyBoxarr and Resilio Sync also use port 8888 by default. If you run either, change only the first number, for example
8889:8888/tcp, and use that port in steps 5 and 6. See Port is already in use. -
Recreate Gluetun and check that it connected, as in steps 4 and 5 of Fix the values in .env. If you installed qBittorrent VPN, recreate it too (step 6).
-
Test it from another computer on your network. It should print the VPN address, not your home address:
Terminal window curl -s -x http://YOUR_PROXY_USER:YOUR_PROXY_PASSWORD@YOUR_SERVER_IP:8888 https://ifconfig.me -
In your browser or device, set the HTTP proxy to
YOUR_SERVER_IPand port8888, with your username and password.
Only traffic from apps you point at the proxy uses the VPN. When Gluetun stops or loses the VPN, the proxy stops working instead of falling back to your home connection. For the other proxy settings, see the HTTP proxy page in the Gluetun wiki.
Installing qBittorrent VPN again keeps these lines. Reinstalling Gluetun replaces gluetun.yml, so add them again after that.
If the adapter is not found
Section titled “If the adapter is not found”Deployrr only checks for the device. It doesn’t create it. These are the two results that stop you:
| What you see | What it means |
|---|---|
No network adapter detected at /dev/net/tun and Network adapter detection completed - No adapter detected |
Your server has no /dev/net/tun device. The menu line stays Not Set/Found. |
Device is not readable or writable by YOUR_USER and Network adapter detection failed - Permission issue detected |
The device exists, but your Linux user can’t read and write it. |
Until the adapter is set, installing Gluetun shows Network Adapter - Must be configured (System menu) in a Requirements Not Met box.
Deployrr gives no steps for this. If your server is a Proxmox LXC container, the device usually has to be passed from the Proxmox host into the container. You set that on the Proxmox host, not in Deployrr. After you change it, restart the container and run System > Network again. Deployrr saves the result, so the menu line only changes when you run it again. The Proxmox steps are in Run Deployrr in a Proxmox LXC container.
To see how the device is passed into an LXC, watch Proxmox LXC network device passthrough at 2:12. The steps are also in UDMS part 10: pass the TUN network device into a Proxmox LXC (manual setup).

