Telefetchr: The Ultimate Self-Hosted Telegram Downloader

Safiyu Vattaparambil — Wed, 17 Dec 2025 13:34:08 +0000

Have you ever tried to backup files from a Telegram channel or download a large series of videos? The native Telegram client is great for chatting, but when it comes to bulk file management, it leaves a lot to be desired. Single-threaded downloads, no advanced filtering, and the need to keep your desktop client open can be a pain.

Enter Telefetchr: a self-hosted, Dockerized web application designed to supercharge your Telegram downloads.

✨ Key Features

Parallel "Chunk & Merge" Downloading
This is the secret sauce. Telegram's API allows searching for files, but downloading them sequentially can be slow due to network latency and protocol overhead.

Telefetchr implements a Chunk & Merge strategy:

Files are split into logical 4MB chunks.
Multiple asynchronous workers download these chunks in parallel to separate temporary files (e.g., video.mp4.part1, video.mp4.part2).
Non-blocking I/O: I use aiofiles to write data without blocking the event loop, ensuring the UI remains responsive.
Once finished, the parts are merged instantly into the final file.
This approach maximizes your bandwidth and solves "disk contention" issues common with simple parallel writers.

Advanced Filtering
Forget scrolling for hours. Telefetchr indexes your channel and lets you filter by:

File Type: Video, Audio, Photo, Document.
Size: Min/Max size constraints (e.g., "> 1GB").
Date: Filtering by upload time-frame.
Search: Full-text search on file captions and names.

Smart Authentication
Security is key for self-hosting. Telefetchr comes with:

JWT Authentication: Secure login for external access.
Trusted Sub-net Bypass: Configure your home network (e.g., 192.168.1.0/24) as "trusted". Devices on your WiFi get instant Admin access without typing passwords, while external access remains locked down.

Docker First
Deploy anywhere. The entire stack (Fast-API back-end + Vanilla JS front-end) is packaged into a lightweight Docker container.

Deployment: via docker compose stack

 telefetchr:
    image: safiyu/telefetchr:latest
    container_name: telefetchr
    volumes:
      - ./downloads:/app/downloads
      - ./sessions:/app/sessions
    environment:
      - PYTHONUNBUFFERED=1
      - API_ID=12345 # your api_id from my.telegram.org
      - API_HASH=saasdasdf12324 # your api_hash from my.telegram.org
      - PHONE_NUMBER=12345 # without + sign
      - MAX_CONCURRENT_DOWNLOADS=3 # optional, default is 3
      - SECRET_KEY=your_generated_secret_key_here # Generate secret: python -c "import secrets; print(secrets.token_urlsafe(32))"
      - ADMIN_USERNAME=yourusername
      - ADMIN_PASSWORD=yourpassword
      - ACCESS_TOKEN_EXPIRE_MINUTES=1440  # 24 hours
      - PUID=1000
      - PGID=1000
      - TRUSTED_SUBNETS=192.168.1.0/24  # Optional auth bypass
    restart: always

Please report bugs and issues at https://github.com/safiyu/telefetchr

DEV Community: Safiyu Vattaparambil

Telefetchr: The Ultimate Self-Hosted Telegram Downloader