Website • Wiki • GitHub • Reddit

qBittorrent is a free, open-source BitTorrent client with a feature-rich web interface. No ads, no bloat — just a powerful torrent client.

• Web UI — Full-featured web interface for remote access
• No Ads — Completely advertisement-free
• RSS Support — Subscribe to feeds with download filters
• Search Engine — Built-in torrent search
• IP Filtering — Block peers with IP filter lists
• Bandwidth Scheduling — Limit speeds by time of day
• Sequential Download — Download files in order for streaming

• Docker and Docker Compose
• One external Docker network (qbittorrent-front)
• Reverse proxy (Caddy, Nginx, Traefik) for public TLS on the WebUI
• A downloads directory on the host, writable by your ${PUID}:${PGID}
• A port on your router/firewall forwarded to the BitTorrent listen port

docker network create qbittorrent-front

cp .env.example .env
nano .env

Required values:

• DOWNLOADS_DIR — absolute host path to your downloads directory (mounted as /downloads inside the container)
• QBT_LEGAL_NOTICE=confirm — the upstream image refuses to start without this; setting it affirms you have read qBittorrent's legal notice

mkdir -p data
docker compose up -d

qBittorrent (>= 4.6.1) generates a temporary admin password on first boot and prints it to stdout:

docker logs qbittorrent 2>&1 | grep -i "temporary password"

1. Visit https://torrent.example.com (or http://localhost:9160 for local testing).
2. Log in as admin with the temporary password from step 4.
3. Immediately change the password in Tools -> Options -> Web UI -> Authentication.
4. Set the default save path under Tools -> Options -> Downloads -> Default Save Path to /downloads (or a subdir like /downloads/movies).

The image's own envs (QBT_VERSION, UMASK, PAGID) are not exposed in this template because the image tag is pinned here and the others are rarely needed. Add them under environment: if you need them — see the upstream image README.

torrent.example.com {
    encode zstd gzip
    reverse_proxy http://127.0.0.1:9160
}

In qBittorrent's WebUI, enable Bypass authentication for clients on localhost (under Web UI -> Authentication) so your reverse proxy doesn't hit the login form on every request. If you front it with Authentik or similar SSO instead, keep auth enabled and pass the proxy headers through.

The BitTorrent listen port has to be reachable from the public internet for inbound peer connections — that is why it is published on all interfaces, not just localhost. Forward it in your router and (if applicable) open it in your host firewall.

Use the same host path in qBittorrent and Jellyfin/Plex so finished downloads appear in your library without a copy step. For example:

# qbittorrent/.env
DOWNLOADS_DIR=/media-data/downloads

# jellyfin docker-compose.yml volumes:
- /media-data/downloads:/media/downloads

Then point your *arr stack (Sonarr, Radarr) at qBittorrent's WebUI and have them move completed files into your media library subdirectories.

This template ships with a hardened default configuration:

• Maintained by the qBittorrent project directly (publisher: sledgehammer999)
• Single-process container — qbittorrent-nox is PID 1, no s6-overlay init layer
• Patched same-day as upstream releases (LSIO typically trails)
• ~190 MB compressed, multi-arch (amd64, arm64, armv7, armv6, riscv64, 386)
• Read-only filesystem capable out of the box (we don't use it here because user: + read-only is incompatible per upstream README)

After login, under Tools -> Options:

• Downloads -> Default Save Path: /downloads (or a subdirectory)
• Downloads -> Keep incomplete torrents in: enable, e.g. /downloads/incomplete
• Connection -> Port used for incoming connections: matches QBT_TORRENT_PORT from .env
• Connection -> Global maximum connections: 500 (default is sensible)
• Web UI -> Bypass authentication for clients on localhost: enable if behind a trusted reverse proxy
• Speed -> Alternative Rate Limits: enable + schedule for off-peak unmetered bandwidth

• Star on GitHub
• Donate
• Report Issues
• Reddit Community

qBittorrent is released under the GPL-2.0 License.