qBittorrent-Auto-Port-Forward

A shell script and Docker container that automatically sets qBittorrent's listening port from a text file.

  • Automation
  • Network Services
  • Tools & Utilities
A shell script and Docker container that automatically sets qBittorrent's listening port from a text file. It is useful when your qBittorrent container is bound to a VPN client (such as WireGuard-PIA or Gluetun) that writes its forwarded port to a file, keeping your client reachable without manual port changes.

Platform availability

Available on 1 of 10 platforms

  • Unraid
  • TrueNAS (not listed)
  • Umbrel (not listed)
  • ZimaOS (not listed)
  • Proxmox (not listed)
  • Helm (not listed)
  • Mac (not listed)
  • Windows (not listed)
  • Linux (not listed)
  • Any server (not listed)

Health score?A 0-100 score computed nightly from four factors: maintained (40%: recent commits and steady activity), popular (25%: GitHub stars, log scale), easy to install (20%: platforms, install notes, setup guides, Docker image) and light to run (15%: minimum RAM, ARM support). When the source code has been checked, a fifth factor, security check (20%: automated scan for committed secrets, unsafe desktop-app settings, known-vulnerable dependencies and project hygiene; any serious finding caps it at 20), is added. Factors without data are left out and the rest are rescaled.

44/100 Fair

Maintained
38last commit 349 days ago
Popular
2927 GitHub stars
Easy to install
351 install platform, install notes, Docker image
Light to run
No data
Security check
85no serious findings, CI

Based on 4 of 5 factors.

Availability: platform listings confirmed today, links checked 44 days ago

GitHub stars
27
Open issues
2
Last commit
2025-12-06
Activity
stale

Checked 19 days ago - source: GitHub (claabs/qbittorrent-port-forward-file)

Resources & Compatibility

ARM (e.g. Raspberry Pi) is supported.

Checked 54 days ago - source: Docker Hub image tags and published docs

First-install notes

  • Match PUID/PGID to your host user Run `id your_user` on the host and put those numbers in PUID/PGID (the user and group IDs the container runs as); wrong values can make the app unable to read/write your files. source
  • Expose the Web UI and torrent ports Map the Web UI port to reach the browser page and map the torrenting port for both TCP and UDP; if they don't match the WEBUI_PORT and TORRENTING_PORT settings, the page may not open or peers may fail. source
  • Keep /config safe and persistent Mount /config to a stable folder on your machine so your login details and settings survive restarts; losing this folder forces you to redo first-run setup. source
  • Have your VPN client write the forwarded port to a file Configure your VPN client to persist its forwarded port to a shared file, for example docker-wireguard-pia with PORT_FORWARDING=1, PORT_PERSIST=1 and PORT_FILE=/pia/forwarded_port.txt, or Gluetun with PRIVATE_INTERNET_ACCESS_VPN_PORT_FORWARDING=on and PRIVATE_INTERNET_ACCESS_VPN_PORT_FORWARDING_STATUS_FILE=/gluetun/forwarded_port.txt, then mount that file into this container. source
  • Set the port file and Web UI address Point PORT_FILE at the text file holding the forwarded port (default /config/forwarded_port.txt) and QBT_ADDR at your qBittorrent Web UI URL (default http://localhost:8080); supply QBT_USERNAME and QBT_PASSWORD for access. source

Fetched 44 days ago - each note links to its source

Alternatives (12)

  • BiglyBT - Source for BiglyBT, a feature filled, open source, ad-free, bittorrent client.
  • Deluge - Deluge is a lightweight, free-software, cross-platform BitTorrent client for downloading and managing torrent files.
  • Free Download Manager - Accelerates downloads by splitting files, supports dark mode, controls traffic, enhances speed, organizes downloads, and is ad-free.
  • LibreTorrent - LibreTorrent is a Free as in Freedom torrent client for Android 4 and later, based on libtorrent.
  • Motrix - Motrix is a full-featured download manager that supports downloading HTTP, FTP, BitTorrent, Magnet, Baidu Net Disk, etc.
  • Rapidbay - Rapid bay is a self hosted video service/torrent client that makes playing videos from torrents dead simple.
  • Tixati - Tixati is a peer-to-peer file sharing program that uses the popular BitTorrent protocol.
  • Transmission - Transmission is a BitTorrent client for downloading and sharing files over the BitTorrent protocol.
  • aria2 - Aria2 is a lightweight, multi-protocol, multi-source, cross-platform command-line download utility that retrieves files over HTTP/HTTPS, FT…
  • gopeed - Gopeed is a free, open-source download manager that handles web links, torrents, magnet links, and ed2k downloads on desktop and mobile pla…
  • qBittorrent - qBittorrent is a free, open-source BitTorrent client that provides a self-hosted web-based interface for downloading, managing, and schedul…
  • µTorrent - Desktop client for large-scale torrent downloads, offering simultaneous downloads, bandwidth optimization, and scheduling.

Checked 40 days ago - source: AlternativeTo

Common questions

How do I configure this for use with docker-wireguard-pia?

Set docker-wireguard-pia to output the forwarded port by using PORT_FORWARDING=1, PORT_PERSIST=1, and PORT_FILE=/pia/forwarded_port.txt. Then make that PIA directory available to this container so it can read the port file.

How does the app connect to qBittorrent?

Set QBT_ADDR to the qBittorrent Web UI HTTP URL, including the port. Also set QBT_USERNAME and QBT_PASSWORD to the qBittorrent Web UI login credentials.

What volume should I mount for the forwarded port file?

Mount the host directory containing the port file to /config in the container as read-only. Set PORT_FILE to the container-side path of that file, such as /config/forwarded_port.txt.

Answers sourced from github.com

Community

Collected 49 days ago - public community threads