Telegram Media Downloader (Desktop)

Cross-platform desktop app (Windows/Linux/macOS) that lets a user sign in to Telegram, pick a chat/channel/group, and download all media.

Tech stack

• Python + Telethon (MTProto)
• Desktop UI: Qt via PySide6
• Async UI: qasync (Qt + asyncio)
• Packaging: PyInstaller (build per-OS)

🚀 Portable & Standalone

No Python installation is required for end-users. When built with the instructions below, PyInstaller bundles the Python interpreter and all necessary libraries into a single executable file. This means you can distribute the .exe (Windows) or .app (macOS) to anyone, and it will run instantly without any prerequisite setup.

---

📖 How to Use

1. Get Your API Credentials

Before you can use the app, you need to obtain API credentials from Telegram:

1. Log in to https://my.telegram.org.
2. Go to API Development Tools and create a new application (you can use any name).
3. Note down your App api_id and App api_hash.

2. Login to the App

1. Enter your Credentials: Paste your api_id and api_hash.
2. Phone Number: Enter the phone number associated with your Telegram account (using international format, e.g., +1234567890).
3. Verification Code: Click Send Code and wait for the verification code to arrive in your official Telegram app. Enter the code in the app.
4. 2FA Password: If you have two-step verification enabled, enter your cloud password when prompted.

3. Scanning Media

1. Select a Chat: Once logged in, pick a contact, group, or channel from the left sidebar.
2. Configure Filters:
   • Since date: (Optional) Use YYYY-MM-DD to only scan media after a certain date.
   • Message limit: (Optional) Limit how many messages to look back through (set to 0 for unlimited).
3. Scan: Click Scan Media. The app will calculate how many photos, videos, and files are available.

4. Downloading

1. Set Output Folder: Click Browse in the options dialog (bottom right settings icon) to choose where to save your media.
2. Filter Types: Check the boxes for the types of media you want (Photos, Videos, Files, etc.).
3. Download: Click Download Selected. You'll see real-time progress and a smooth animation while the files are being saved.

---

Project layout

my_qt_app/
├── data/
├── docs/
├── src/
│   └── app/
│       ├── main.py
│       ├── core/
│       ├── ui/
│       └── ...
├── tests/
├── scripts/
├── pyproject.toml
└── run_desktop.py

Setup (dev)

Windows PowerShell:

python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install -U pip
python -m pip install -e ".[dev]"
python run_desktop.py

Build (PyInstaller)

PyInstaller builds are OS-specific. You must build on the target operating system (e.g., build on Windows to get a .exe, build on macOS to get an .app).

🪟 Windows (Powershell)

pyinstaller --noconfirm --onefile --windowed `
    --name "Telegram Downloader" `
    --icon "data/icons/telegram-downloader-icon.ico" `
    --add-data "data/icons/*;data/icons" `
    --add-data "data/styles/*;data/styles" `
    --paths "src" `
    run_desktop.py

🍎 macOS (Terminal)

Note: Uses : separator for data paths instead of ;.

pyinstaller --noconfirm --onefile --windowed \
    --name "Telegram Downloader" \
    --icon "data/icons/telegram-downloader-icon.icns" \
    --add-data "data/icons/*:data/icons" \
    --add-data "data/styles/*:data/styles" \
    --paths "src" \
    run_desktop.py

🐧 Linux (Terminal)

Note: Uses : separator for data paths instead of ;.

pyinstaller --noconfirm --onefile --windowed \
    --name "Telegram Downloader" \
    --icon "data/icons/telegram-downloader-icon.png" \
    --add-data "data/icons/*:data/icons" \
    --add-data "data/styles/*:data/styles" \
    --paths "src" \
    run_desktop.py

Output will be located in the dist/ folder.