qBittorrent & Private Internet Access VPN Docker

A Docker container combining qBittorrent with Private Internet Access (PIA) VPN, supporting both WireGuard and OpenVPN. Built on Alpine Linux for a minimal footprint.

Fork of j4ym0/pia-qbittorrent with bug fixes and additional features.

Quick Links

Companion App

Looking for a native Windows desktop experience? Check out the companion Electron app that wraps the qBittorrent Web UI:

qBittorrent Desktop for Windows 11 — native window, system tray, magnet link support, .torrent file association, and the running container version shown in the title bar.

The title-bar version comes from an X-Docker-Version response header this image adds to the Web UI (set from the image version on every start), so the app always shows which build is running.

Features

• WireGuard and OpenVPN support
• PIA port forwarding for seeding
• PIA server list fetched directly from PIA at build time — every image ships with the current region list
• Kill switch — all IPv4 and IPv6 traffic blocked if the VPN drops
• Multi-arch images — amd64 and arm64
• VPN network interface auto-detected and locked (WireGuard pia / OpenVPN tun0)
• Configurable UID/GID for correct file ownership on Unraid and NAS systems
• Configurable UMASK; download folder permissions preserved across restarts
• Automatic .torrent file export to /downloads/torrents
• Graceful shutdown — saves resume data so torrents resume instead of re-checking after an update
• Secure credential storage via auth.conf
• DNS leak protection with custom DNS servers
• Hook script support after the VPN connects
• Web UI accessible on your local network

Components

Quick Start

docker run -d --init --name=pia-qbittorrent --restart unless-stopped \
  --cap-add=NET_ADMIN \
  -v /your/downloads:/downloads \
  -v /your/config:/config \
  -p 8888:8888 \
  -e PIA_USERNAME=your_username \
  -e PIA_PASSWORD=your_password \
  -e PIA_REGION=ca_montreal \
  -e VPN_CLIENT=wireguard \
  -e UID=99 \
  -e GID=100 \
  -e UMASK=000 \
  gjergjk/pia-qbittorrent:latest

Environment Variables

Volumes

Unraid Setup

Set the following container variables for correct file ownership:

This maps qBittorrent to Unraid's nobody:users so downloaded files are accessible from SMB shares.

Network type: leave it on Bridge (the Unraid default). The VPN tunnel runs entirely inside the container, so no special network mode is needed.

VPN Client

WireGuard

• Lower CPU usage and faster speeds due to less overhead
• Requires Linux kernel 5.6+
• Port forwarding works in most regions but may have issues in some
• Best for stable home networks

OpenVPN

• Broader compatibility
• Better for unusual network configurations or high latency
• More reliable port forwarding

Note: Port forwarding is available in most PIA regions, but not all. See the PIA Regions section for the full list of regions that support it.

PIA Regions

Set PIA_REGION to the region you want. Matching is flexible — you can use the region name or its PIA ID, and it's case-insensitive (underscores, hyphens, and spaces are treated the same). So ca_montreal, CA Montreal, and ca all resolve to the same region.

Common regions with port forwarding:

ℹ️ Most PIA regions support port forwarding, but not all. The regions listed above are confirmed to support it. To use a different region with PORT_FORWARDING=true, see the full list of port-forwarding regions below.

All port-forwarding regions

This list comes directly from PIA and is refreshed into the image at build time, so the bundled data.json always matches PIA's current servers. To regenerate the readable list yourself:

curl -s https://serverlist.piaservers.net/vpninfo/servers/v6 | head -1 | \
  jq -r '.regions[] | select(.port_forward) | "\(.name) — \(.id)"' | sort

Port Forwarding

Enabled by default (PORT_FORWARDING=true). On startup a port is requested from PIA, opened in the firewall, and set in qBittorrent automatically.

• Port is assigned randomly by PIA — you cannot specify one
• Port is valid for up to 2 months
• Container refreshes the port binding every 10 minutes to keep it alive
• If your region doesn't support port forwarding (e.g. all US regions), the container logs a warning and keeps running without it — it no longer crashes. Pick a supported region to use it.
• If the container restarts too frequently (20+ times in 30 mins) you may hit PIA's rate limit — stop the container and wait 1 hour

Web UI

Access at http://YOUR_SERVER_IP:8888

Default username: admin Default password: shown in container logs (docker logs pia-qbittorrent)

Change the password after first login — it changes every restart until you set a permanent one.

Saving .torrent Files

By default, added .torrent files are automatically saved to /downloads/torrents so you always keep a copy. The folder is created automatically when you add your first torrent.

Magnet links are saved too — just a few seconds later. A magnet has no metadata when added, so qBittorrent writes the .torrent once it fetches the metadata from the swarm. (If a magnet never finds peers, no file is written — but it wouldn't download anyway.)

Existing installs: this default is only written on a fresh config, so if you upgraded from an earlier version it won't appear automatically. To enable it manually, go to Options → Downloads → Saving Management, tick "Copy .torrent files to:", enter /downloads/torrents, and Save.

auth.conf File

Store credentials securely by mounting an auth file instead of using environment variables:

/your/auth.conf:
line 1: your_pia_username
line 2: your_pia_password

docker run ... -v /your/auth.conf:/auth.conf ...

When /auth.conf is present, PIA_USERNAME and PIA_PASSWORD are ignored.

Hooks

Create /config/post-vpn-connect.sh to run custom code after the VPN connects but before qBittorrent starts. Runs as root.

Available variables:

Example:

MY_IP=$(wget -qO- ifconfig.me/ip)
printf " My external IP is $MY_IP\n"
printf " My forwarding port is $PF_PORT\n"

DNS Servers

Once connected to PIA you can also use PIA's private DNS: 10.0.0.242

Build from Source

git clone https://github.com/GeorgeAL78/pia-qbittorrent-docker.git
cd pia-qbittorrent-docker
docker build -t gjergjk/pia-qbittorrent .

Known Issues

• Banned client error on some trackers

  • Some private trackers may not have whitelisted the current qBittorrent version yet
  • Check the tracker's forum for supported client versions

• Port forwarding rate limit

  • If the container restarts more than 20 times in 30 minutes, PIA will rate limit port forwarding requests
  • Fix: Stop the container and wait 1 hour

• Special characters in password

  • If your password contains special characters use the /auth.conf file instead of environment variables

• Unauthorized when using proxy for WebUI

  • Fix: Set CSRFPROTECTION=false

• nft: Protocol not supported

  • Occurs on older kernels or Synology NAS
  • Fix: Set LEGACY_IPTABLES=true

• Files moved to .trash instead of deleted

  • qBittorrent 5.x defaults to moving files to trash
  • Fix: Tools → Options → Advanced → set "Torrent content removing mode" to "Delete files permanently"

Changelog

See Docker Hub for full changelog.

License

GNU General Public License v3.0

This project is a fork of j4ym0/pia-qbittorrent-docker, originally MIT licensed. The original MIT notice is preserved in the NOTICE file.

Disclaimer

This is an unofficial, community-maintained project. It is not affiliated with, endorsed by, or sponsored by Private Internet Access or qBittorrent. "Private Internet Access", "PIA", and "qBittorrent" are trademarks of their respective owners and are used here only to describe compatibility.