qBittorrent VPN Docker: Complete Setup & Gluetun Guide (2026)
Setup qBittorrent VPN in Docker with Gluetun, Proton VPN, or PureVPN. Fix WebUI access, bind network interfaces, enable kill switch, and route Arr stacks.
Quick Answer: How to Run qBittorrent VPN in Docker Safely
The recommended modern architecture is running a Gluetun VPN sidecar container alongside a lightweight qBittorrent image (such as linuxserver/qbittorrent) using Docker Compose with network_mode: "service:gluetun". Gluetun handles WireGuard or OpenVPN tunnels and enforces a strict iptables kill switch. Crucially, ports must be exposed on the Gluetun container, not qBittorrent, and local subnets must be whitelisted via FIREWALL_OUTBOUND_SUBNETS to access the WebUI locally.
Deploying qbittorrentvpn docker containers is the gold standard for automated homelabs, media servers, and NAS boxes. In theory, it delivers 24/7 autonomous downloads, automated media management, and ironclad privacy with zero host system clutter.
In practice, setting up a docker qbittorrent vpn stack is notorious for causing massive headaches:
You spin up the container and immediately get "Connection Refused" at localhost:8080 because the VPN kill switch blocks local subnet traffic.
Torrents stall at 0% or crawl at 40 KB/s because the Docker container has no forwarded inbound port, turning your client into an unconnectable passive peer.
Users wonder whether to route Sonarr, Radarr, and Prowlarr through the VPN, inadvertently getting their indexer API keys blacklisted by Cloudflare CAPTCHAs.
Why Use Docker for qBittorrent? Gluetun vs. binhex-qbittorrentvpn vs. Hotio
Should I run qBittorrent through Docker containers? Decoupled sidecar vs. all-in-one monolithic images.
When searching for a docker image for qbittorrent with vpn, beginners are often confused between two competing approaches on Docker Hub:
The Modern Sidecar Model: Gluetun + LinuxServer
You run Gluetun as a dedicated VPN network gateway, and attach a lightweight linuxserver/qbittorrent container using network_mode: "service:gluetun".
- Decoupled upgrades: You can update qBittorrent without breaking your VPN handshake, or update WireGuard without touching torrent configs.
- Kernel-level Kill Switch: Gluetun enforces Linux
iptablesthat drop 100% of packets exiting non-VPN interfaces. - Shared tunnel: You can route other downloaders through the same single VPN tunnel.
The All-in-One Model: binhex-qbittorrentvpn & hotio
Containers like binhex/arch-qbittorrentvpn or hotio/qbittorrent bake OpenVPN and qBittorrent into a single large Docker container image.
- Popular on Unraid Community Applications due to easy GUI templates.
- Heavier container footprint with slower base image updates.
- Difficult to customize when providers change WireGuard endpoints or key exchange mechanics.
| Docker Architecture Metric | Gluetun + qBittorrent (Recommended) | binhex-qbittorrentvpn | hotio/qbittorrent |
|---|---|---|---|
| Architecture Model | Decoupled Sidecar (Gluetun + linuxserver/qbittorrent) | Monolithic All-in-One (binhex-qbittorrentvpn) | Integrated Container (hotio/qbittorrent) |
| VPN Protocol Flexibility | Native WireGuard & OpenVPN with custom providers | Primarily OpenVPN; complex WireGuard setup | WireGuard & OpenVPN built-in |
| Kill Switch Reliability | Kernel iptables blocking non-VPN egress in network namespace | Container iptables scripts | Internal routing rules |
| Independent Client Updates | Yes (Update qBittorrent without touching VPN tunnel) | No (Must wait for maintainer to release new base image) | Moderate (Tied to hotio build cadence) |
| Multi-Container Routing | Yes (Can route other containers through the same tunnel) | No (Locked strictly to internal qBittorrent daemon) | No (Single container) |
| WebUI Port Exposure | Exposed via Gluetun container with LAN subnet rule | Exposed directly on container host port | Exposed directly with WebUI port environment |
gluetun qbittorrent docker compose: Production Blueprint
Select your VPN provider to generate a tested, leak-proof docker-compose.yml file.
version: "3.8"
services:
gluetun:
image: qmcgaw/gluetun:latest
container_name: gluetun
cap_add:
- NET_ADMIN
devices:
- /dev/net/tun:/dev/net/tun
ports:
- 8080:8080/tcp # qBittorrent WebUI (accessed via Gluetun)
- 6881:6881/tcp # Torrent peer listening port (TCP)
- 6881:6881/udp # Torrent peer listening port (UDP)
environment:
- VPN_SERVICE_PROVIDER=protonvpn
- VPN_TYPE=wireguard
- WIREGUARD_PRIVATE_KEY=your_proton_private_key_here
- WIREGUARD_ADDRESSES=10.2.0.2/32
- SERVER_COUNTRIES=Netherlands
# LAN subnet whitelist: allows local PCs to access WebUI at :8080
- FIREWALL_OUTBOUND_SUBNETS=192.168.1.0/24,10.0.0.0/8
- FIREWALL_VPN_INPUT_PORTS=6881
restart: unless-stopped
qbittorrent:
image: lscr.io/linuxserver/qbittorrent:latest
container_name: qbittorrent
# Crucial: routes all network traffic through Gluetun's VPN namespace
network_mode: "service:gluetun"
environment:
- PUID=1000
- PGID=1000
- TZ=UTC
- WEBUI_PORT=8080
volumes:
- ./config:/config
- /mnt/storage/downloads:/downloads
depends_on:
gluetun:
condition: service_healthy
restart: unless-stoppedqBittorrent Docker VPN WebUI Local Access: The 2 Mandatory Rules
How to access qBittorrent in Docker without triggering "Connection Refused" or leaking your IP.
Trap 1: Mapping Ports on qBittorrent Instead of Gluetun
When a container uses network_mode: "service:gluetun", Docker completely strips its independent virtual network adapter. The container shares Gluetun's network namespace.
If you put ports: - 8080:8080 under the qbittorrent service block, Docker will fail with a fatal syntax error. All ports must be exposed on the gluetun service block.
Trap 2: Forgetting FIREWALL_OUTBOUND_SUBNETS
Gluetun's default kill switch blocks any traffic trying to reach local non-VPN networks. When your laptop at 192.168.1.50 tries to open http://192.168.1.100:8080, Gluetun drops the packet.
The Fix:
FIREWALL_OUTBOUND_SUBNETS=192.168.1.0/24,10.0.0.0/8
This whitelists your local home subnet so all home devices can access the WebUI cleanly.
Docker Arr Stack qBittorrent on VPN: Should You Route Everything?
How to route only qBittorrent Docker traffic through VPN while keeping Sonarr, Radarr, and Prowlarr unblocked.
The Dangerous Arr Stack VPN Mistake
The Optimal Homelab Routing Strategy:
Give qBittorrent network_mode: "service:gluetun". All torrent hashes, tracker announces, and P2P chunk transfers are 100% encrypted and protected by the VPN kill switch.
Run your *arr apps on a standard Docker bridge network. Inside Sonarr's "Download Clients" settings, set the host to http://gluetun:8080 (or your Docker host LAN IP). Sonarr communicates with qBittorrent locally, while fetching metadata using your clean residential connection.
Verification Commands: Check Public IP, Logs, and Stop State
Essential CLI commands to verify leak protection and manage running containers.
Check Active VPN IP
Run from host terminal to verify qBittorrent is using the VPN IP:
docker exec -it gluetun wget -qO- https://ipinfo.io
Ensure the returned IP matches your VPN server location.
View qBittorrent Logs in Docker
Inspect real-time initialization and tracker errors:
docker logs -f qbittorrent
Check Gluetun handshake with docker logs -f gluetun.
docker compose stop Ubuntu / WSL
What happens to downloads when stopping?
Docker sends SIGTERM to qBittorrent. The daemon safely writes fastresume data to disk within a 10s grace period. Downloads resume perfectly on restart.
Best VPN for qBittorrent Docker: Port Forwarding & WireGuard Integration
Why NordVPN and Mullvad fail in Docker, and why Proton VPN and PureVPN deliver maximum line speeds.
Many users search for "ubuntu docker nordvpn qbittorrent" or "qbittorrent vpn docker mullvad". However, NordVPN does not support port forwarding, leaving your container permanently firewalled. Mullvad completely removed port forwarding in 2023. For healthy seeding and maximum download speeds in Docker, these audited providers lead the industry:
Proton VPN
- Official 1-click Gluetun integration via WireGuard configuration
- Active Port Forwarding (NAT-PMP) supported inside Docker tunnels
- Exclusive Moderate NAT feature for gaming and peer discovery
- Cross-platform native support: Linux, Docker, Synology, Unraid, Windows, Mac
- Audited Swiss zero-logs jurisdiction outside US/EU data retention laws
- 30-day money-back guarantee with zero risk
PureVPN
- Full multi-port forwarding support: route multiple custom ports in Docker
- Ideal for hosting Docker game servers, TrueNAS seedboxes, and remote web panels
- Works seamlessly on Synology Container Manager, Unraid, and Portainer
- KPMG Always-On audited zero-logs policy with British Virgin Islands privacy
- P2P-optimized 10 Gbps network with high-speed WireGuard tunnels
- Sub-$2.20/mo long-term plan with a 31-day unconditional money-back trial
This page contains affiliate links. If you sign up through them, NAT Checker may earn a commission at no extra cost to you.
qBittorrent Docker VPN FAQ
Direct answers to the most common configuration and troubleshooting questions from Reddit and Portainer forums.
Related Docker & Torrenting Guides
Continue optimizing your homelab network and BitTorrent performance: