Deluge BitTorrent Client

beginner

Lightweight, cross-platform BitTorrent client.

Overview

Deluge is a lightweight, full-featured BitTorrent client built in Python that has been actively developed since 2006. Originally created as an alternative to heavier torrent clients, Deluge features a unique daemon/client architecture that separates the core torrent engine from the user interface, allowing for flexible deployment scenarios including headless server operations. The client supports all modern BitTorrent protocol features including DHT, PEX, UPnP, and encryption while maintaining a small resource footprint. This Docker configuration deploys Deluge as a containerized torrent client with persistent storage for both configuration data and downloaded files. The setup exposes both the web interface port (8112) and the BitTorrent protocol ports (6881) while maintaining proper file permissions through PUID/PGID mapping. The containerized approach isolates the torrent client from the host system while providing controlled access to download directories and configuration persistence. This stack is ideal for users who need a reliable, always-on torrent client without the overhead of desktop applications. Home media server administrators, seedbox operators, and developers building automated download workflows will benefit from Deluge's plugin architecture, web-based management interface, and daemon-mode operation that continues running independently of user sessions.

Key Features

Daemon/client architecture enabling headless server operation with remote management capabilities
Comprehensive plugin ecosystem including AutoAdd, Label, Scheduler, and Execute plugins for automation
Multi-interface support with GTK desktop client, web interface, and console client options
Advanced bandwidth management with global and per-torrent speed limiting and scheduling
Complete BitTorrent protocol implementation including magnet links, DHT, PEX, and protocol encryption
Flexible authentication system supporting multiple user accounts with different permission levels
RSS feed integration and automatic torrent management through plugin extensions
Cross-platform compatibility with consistent behavior across Linux, Windows, and macOS environments

Common Use Cases

1Home media server automation for downloading Linux distributions and open-source software releases
2Seedbox deployment on VPS or dedicated servers for high-ratio torrent seeding operations
3Corporate environments distributing large software packages or datasets via BitTorrent protocol
4Development teams automating nightly builds and asset distribution through torrent networks
5Educational institutions managing legal content distribution with bandwidth scheduling
6Remote torrent management where users need to control downloads from mobile devices or other locations
7Multi-user torrent environments with isolated download directories and access controls

Prerequisites

Docker and Docker Compose installed with at least 512MB available RAM for container operation
Network ports 8112, 6881 TCP/UDP available and properly forwarded through firewall/router
Sufficient disk space in the downloads directory with write permissions for PUID 1000
Basic understanding of BitTorrent protocols and legal considerations for torrent usage
Network configuration allowing incoming connections for optimal seeding performance
Time zone configuration knowledge for proper scheduler plugin functionality

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  deluge: 
3    image: lscr.io/linuxserver/deluge:latest
4    container_name: deluge
5    environment: 
6      - PUID=1000
7      - PGID=1000
8      - TZ=UTC
9      - DELUGE_LOGLEVEL=error
10    volumes: 
11      - deluge-config:/config
12      - /path/to/downloads:/downloads
13    ports: 
14      - "8112:8112"
15      - "6881:6881"
16      - "6881:6881/udp"
17    networks: 
18      - deluge-network
19    restart: unless-stopped
20
21volumes: 
22  deluge-config: 
23
24networks: 
25  deluge-network: 
26    driver: bridge

.env Template

.env

1# Deluge
2# Default web password: deluge
3# Change /path/to/downloads to your directory

Usage Notes

1Web UI at http://localhost:8112
2Default password: deluge
3Plugin ecosystem
4Daemon/client architecture
5Label and scheduler plugins

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  deluge:
5    image: lscr.io/linuxserver/deluge:latest
6    container_name: deluge
7    environment:
8      - PUID=1000
9      - PGID=1000
10      - TZ=UTC
11      - DELUGE_LOGLEVEL=error
12    volumes:
13      - deluge-config:/config
14      - /path/to/downloads:/downloads
15    ports:
16      - "8112:8112"
17      - "6881:6881"
18      - "6881:6881/udp"
19    networks:
20      - deluge-network
21    restart: unless-stopped
22
23volumes:
24  deluge-config:
25
26networks:
27  deluge-network:
28    driver: bridge
29EOF
30
31# 2. Create the .env file
32cat > .env << 'EOF'
33# Deluge
34# Default web password: deluge
35# Change /path/to/downloads to your directory
36EOF
37
38# 3. Start the services
39docker compose up -d
40
41# 4. View logs
42docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/deluge-torrent/run | bash

Troubleshooting

Web interface shows 'Connection failed' error: Verify container is running and port 8112 is accessible, check firewall settings blocking web interface access
Downloads fail with permission errors: Ensure the downloads directory has correct ownership matching PUID/PGID environment variables (1000:1000)
Low download speeds or no incoming connections: Configure port forwarding for 6881 TCP/UDP on router and verify firewall allows BitTorrent traffic
Plugins not loading or functioning: Check Deluge logs for plugin errors and verify plugin compatibility with current Deluge version in container
Container fails to start with config errors: Remove or backup existing config volume and restart container to regenerate default configuration files
Memory usage grows excessively: Adjust cache settings in Preferences > Cache and limit maximum connections per torrent to reduce memory consumption

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

deluge

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download