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

• Your real IP stays hidden - if the VPN drops, the container loses its internet instead of quietly falling back to your normal connection
• It fixes itself - it notices when the VPN has stopped working - including when it still looks connected - and repairs it without you doing anything
• A dead VPN server is not your problem - it moves to another server nearby, and your forwarded port moves with it
• It keeps up with PIA - the list of PIA servers is refreshed every time the container starts, so it still works when PIA moves a region onto new machines
• Faster seeding - PIA port forwarding is set up for you, wherever your region supports it
• Downloads survive updates - it saves your progress on shutdown, so nothing re-checks after a restart
• Files land with the right owner - so they are readable on Unraid and other NAS systems without fixing permissions afterwards
• Your PIA login can stay out of the container settings - keep it in a protected file instead
• Runs on a Raspberry Pi - as well as a normal PC or server

Components

Quick Start

Requires an active PIA subscription. Get one here — that is a referral link, which supports this project at no extra cost to you.

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

Then open the Web UI on port 8888. --cap-add=NET_ADMIN is required (the VPN and kill switch need it) and --restart unless-stopped is strongly recommended so the container can restart itself to recover from an expired VPN token. UID=99/GID=100/UMASK=000 suit Unraid; see Environment Variables for other systems.

Environment Variables

Volumes

Unraid Setup

Available in Community Applications: search for pia-qbittorrent.

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

• Storage: map /downloads to your share (e.g. /mnt/user/downloads/) and /config to appdata (e.g. /mnt/user/appdata/pia-qbittorrent/).
• Network: Bridge and custom bridge networks both work; the VPN tunnel runs inside the container either way. Avoid Host networking: the container would then share the Unraid server's own network stack, so the kill switch's firewall rules, routes and IPv6 settings would be applied to the server — including flushing the iptables rules Docker itself relies on, which breaks networking for other containers.
• Extra Parameters: keep --cap-add=NET_ADMIN --restart unless-stopped.
• Other containers (Sonarr, Radarr, etc.): if they are on a different Docker network and cannot reach the Web UI, add their subnet to EXTRA_SUBNETS, e.g. 172.18.0.0/16.

VPN Client

WireGuard

• Lower CPU usage and faster speeds due to less overhead
• Needs WireGuard support in the host kernel (built in since Linux 5.6; Unraid has it)
• Best for most home setups

OpenVPN

• Works where WireGuard cannot, e.g. an older kernel without WireGuard
• Can be steadier on unusual networks or high-latency links

Port forwarding, reconnects and server failover work the same on both.

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:

ℹ️ 135 of 190 regions support port forwarding; no US region does. The table below says which. Ignore the -pf in a region id — 32 ids end in -pf without supporting it.

All PIA regions

Either column works as PIA_REGION, as does any unique fragment — massachusetts finds us_massachusetts-pf. Short fragments can be ambiguous, so prefer the full name or id if in doubt.

The container refreshes this list from PIA on every start, so it is never limited to the table below. To regenerate the table yourself:

curl -s https://serverlist.piaservers.net/vpninfo/servers/v6 | head -1 | \
  jq -r '.regions[] | "\(.name) — \(.id) — pf=\(.port_forward)"' | 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 PIA cannot provide a port at startup, the container runs without one and retries every 10 minutes while the VPN is up; once it works, the port is opened and qBittorrent is switched to it automatically. The log shows PIA's reason.
• If your region doesn't support port forwarding (e.g. all US regions), the container logs it and keeps running without it. Pick a supported region to use it.
• PIA limits how often an account can sign in. Restarting the container many times in a short period can hit that limit — see Known Issues

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.

It runs as qbtUser, not root. A hook that needs root must be baked into the image at /app/post-vpn-connect.sh, which the container user cannot write.

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 own private DNS. These are reachable only through the tunnel, so they cannot be used before the VPN is up:

Build from Source

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

Reading the startup log

The first line reports whether the PIA server list could be refreshed:

All three are normal — the container works either way.

Port forwarding, if it could not be set up straight away:

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

• PIA sign-in limit after many restarts

  • PIA limits how often an account can sign in, and every container start signs in. After many restarts in a short period PIA refuses with Try again later., and port forwarding cannot be set up
  • Fix: stop restarting and wait — in testing the limit cleared within 30 minutes. A running container retries port forwarding on its own, so no further restart is needed

• 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

• Cannot block IPv6: ip6tables is unavailable

  • The kill switch blocks IPv6 with ip6tables. On a host that has no IPv6 support in its kernel or iptables build, the container refuses to start rather than run with IPv6 unprotected
  • The container cannot fall back to sysctl at runtime: Docker mounts /proc/sys read-only, so the write silently has no effect
  • Fix: set them when creating the container - --sysctl net.ipv6.conf.all.disable_ipv6=1 --sysctl net.ipv6.conf.default.disable_ipv6=1, or the equivalent commented-out sysctls: block in docker-compose.yml

• 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"

Exit Codes

The container exits with these codes. Codes 5 and 7 expect a restart policy (--restart unless-stopped); without one the container stays stopped. Existing containers can be updated in place with docker update --restart unless-stopped <name>.

Before exiting with 5 the container stops qBittorrent gracefully so resume data is saved and torrents do not re-check on the next start.

Changelog

Every release and its notes are on GitHub Releases. A summary of recent changes is on Docker Hub.

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.