Telegram Media Downloader

A self-hosted daemon that automatically downloads media from Telegram channels, groups, and forum topics. Configure once, run forever.

Looking for a telegram-download-daemon alternative? See Moving from telegram-download-daemon for a settings map and a before and after docker-compose.yml.

Documentation | Quick Start | Examples

Telegram is great for sharing files, but manually downloading from multiple sources is tedious. This tool runs in the background and:

• Downloads new files as they're posted
• Filters by extension, size, date, or filename pattern
• Organizes files into folders by source
• Skips duplicates automatically
• Tracks downloads persistently so files aren't re-downloaded after being moved or renamed
• Sends notifications when downloads complete

• Docker and Docker Compose
• Telegram API credentials from my.telegram.org/apps
• Telegram account with access to the channels/groups you want to download from

mkdir telegram-downloader && cd telegram-downloader

cat > docker-compose.yml << 'EOF'
services:
  telegram-downloader:
    image: rfsbraz/telegram-downloader:latest
    restart: unless-stopped
    environment:
      - TDL_API_ID=YOUR_API_ID
      - TDL_API_HASH=YOUR_API_HASH
      - TDL_PHONE_NUMBER=+1234567890
      - TDL_DAEMON_ENABLED=true
      - TDL_DAEMON_CHECK_INTERVAL=300
      - TDL_SOURCES_0_URL=https://t.me/example_channel
    volumes:
      - ./downloads:/downloads
      - ./sessions:/app/.sessions
    stdin_open: true
    tty: true
EOF

docker compose run --rm telegram-downloader

On first run, you'll be prompted for the Telegram verification code sent to your phone. After authentication, restart with docker compose up -d for daemon mode.

All configuration is done via environment variables with the TDL_ prefix. See the full configuration reference for all options.

# Public channel
- TDL_SOURCES_0_URL=https://t.me/channel_name

# Private channel/group (use the t.me/c/ link format)
- TDL_SOURCES_1_URL=https://t.me/c/1234567890/1

# Forum topic (chat_id/topic_id)
- TDL_SOURCES_2_URL=https://t.me/c/1234567890/123

# File extensions (comma-separated)
- TDL_SOURCES_0_FILTERS_EXTENSIONS=.pdf,.epub,.mobi

# Size limits
- TDL_SOURCES_0_FILTERS_MIN_SIZE=100KB
- TDL_SOURCES_0_FILTERS_MAX_SIZE=500MB

# Global defaults (apply to all sources)
- TDL_GLOBAL_FILTERS_EXTENSIONS=.pdf,.epub

- TDL_DAEMON_ENABLED=true
- TDL_DAEMON_CHECK_INTERVAL=300  # seconds between checks

Run a command after each successful download - extract archives, convert formats, trigger library scans, move files to watch folders:

- TDL_POST_DOWNLOAD_HOOK=unrar x "{file}" "{dir}"
- TDL_POST_DOWNLOAD_HOOK_TIMEOUT=300  # seconds, default 300

Available placeholders: {file} (absolute path), {dir} (parent directory), {filename}, {extension}, {source} (source display name), {size} (bytes).

The command runs without a shell (filenames can't inject arguments) and a hook failure never marks the download as failed.

Control when checks run and how fast downloads go - useful for metered connections or shared networks:

# Only run download checks inside these windows (24h, local time via TZ).
# Multiple windows and cross-midnight windows are supported.
- TDL_SCHEDULE_ACTIVE_HOURS=02:00-08:00,22:00-23:59

# Cap aggregate download speed across all concurrent downloads
- TDL_MAX_DOWNLOAD_SPEED=5MB

Outside active hours the daemon stays alive (health checks keep passing) but skips download checks. A download already in flight when a window closes is never interrupted. Both settings default to unrestricted.

- TDL_NOTIFICATIONS_ENABLED=true
- TDL_NOTIFICATIONS_DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...

# User/group ID for file permissions (arr-stack compatible)
- PUID=1000
- PGID=1000

# Timezone
- TZ=Europe/Lisbon

# Store all files in download_dir without per-channel subfolders
- TDL_FLAT_STRUCTURE=true

# Persistent download tracking (enabled by default)
# When enabled, files won't be re-downloaded after being moved/renamed
- TDL_TRACK_DOWNLOADS=true

Complete Docker Compose configurations for common use cases:

Available from Docker Hub and GitHub Container Registry:

# Docker Hub
docker pull rfsbraz/telegram-downloader:latest

# GitHub Container Registry
docker pull ghcr.io/rfsbraz/telegram-downloader:latest

Multi-arch: linux/amd64 and linux/arm64 (Raspberry Pi 4+, Apple Silicon, AWS Graviton).

See the troubleshooting guide for more.

git clone https://github.com/rfsbraz/telegram-downloader.git
cd telegram-downloader
pip install -r requirements.txt

make test          # all tests with coverage
make unit          # unit tests only
make integration   # integration tests only
make build         # build Docker image
make run           # build + docker compose up

See CONTRIBUTING.md for full development guidelines.

MIT - see LICENSE for details.

• Pyrogram - Telegram MTProto API framework
• Pydantic - Data validation
• docker/metadata-action - Docker tagging

If you find this useful and want to support development, you can buy me a coffee - no pressure at all, just a nice way to say thanks.