# Deluge BitTorrent Client

> Lightweight, cross-platform BitTorrent client.

- Category: Media & Entertainment
- Difficulty: beginner
- Components: deluge
- Tags: torrent, deluge, download, lightweight, python
- Source: https://docker.recipes/media/deluge-torrent

## 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.

## 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

## Use cases

- Home media server automation for downloading Linux distributions and open-source software releases
- Seedbox deployment on VPS or dedicated servers for high-ratio torrent seeding operations
- Corporate environments distributing large software packages or datasets via BitTorrent protocol
- Development teams automating nightly builds and asset distribution through torrent networks
- Educational institutions managing legal content distribution with bandwidth scheduling
- Remote torrent management where users need to control downloads from mobile devices or other locations
- Multi-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

## docker-compose.yml

```yaml
services:
  deluge:
    image: lscr.io/linuxserver/deluge:latest
    container_name: deluge
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=UTC
      - DELUGE_LOGLEVEL=error
    volumes:
      - deluge-config:/config
      - /path/to/downloads:/downloads
    ports:
      - "8112:8112"
      - "6881:6881"
      - "6881:6881/udp"
    networks:
      - deluge-network
    restart: unless-stopped

volumes:
  deluge-config:

networks:
  deluge-network:
    driver: bridge
```

## .env

```bash
# Deluge
# Default web password: deluge
# Change /path/to/downloads to your directory
```

## Usage notes

- Web UI at http://localhost:8112
- Default password: deluge
- Plugin ecosystem
- Daemon/client architecture
- Label and scheduler plugins

## 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

