Quick Start Guide
Get up and running with tgdl in just 5 minutes!
Prerequisites
Before you begin, ensure you have:
- ✅ Installed tgdl
- ✅ Obtained API credentials
- ✅ Your Telegram phone number
Step 1: Login to Telegram
Run the login command:
You'll be prompted for:
- API ID - Your numeric API identifier
- API Hash - Your secret API hash
- Phone number - With country code (e.g., +1234567890)
- Verification code - Sent to your Telegram app
- 2FA password - If you have two-factor authentication enabled
Example Login Session
$ tgdl login
🔐 Telegram Login
Get your API credentials from: https://my.telegram.org/apps
Telegram API ID: 12345678
Telegram API Hash: 0123456789abcdef0123456789abcdef
Phone number (with country code): +1234567890
Sending verification code to +1234567890...
Enter the verification code you received: 12345
✓ Successfully logged in as John Doe (ID: 123456789)
✓ Session saved successfully!
You can now use other tgdl commands.
Two-Factor Authentication
If you have 2FA enabled, you'll be prompted for your password after entering the verification code.
Step 2: List Your Channels/Groups
Check what's available to download:
List Channels
Output:
📢 Fetching your channels...
📢 Found 3 channels:
ID Title Username
===============================================================================
1234567890 Tech News Daily @technews
9876543210 Photography World N/A
5555555555 Movies & TV @moviesandtv
💡 Tip: Use 'tgdl download -c <ID>' to download from a channel
List Groups
List Bot Chats
Step 3: Download Media
Now you're ready to download!
Basic Download (All Media)
Download everything from a channel:
Download with Confirmation
📥 Download Settings
Entity: Channel 1234567890
Media types: all
Parallel downloads: 5
Output: downloads
💡 Tip: Files already downloaded will be skipped automatically
⚠️ Press Ctrl+C to cancel at any time
Continue with download? [Y/n]: y
Fetching messages from entity 1234567890...
Found 125 media files to download
Downloading: 100%|████████████████████| 125/125 [02:15<00:00, 1.08s/file]
✓ Successfully downloaded 125 files!
Files saved to: F:\Downloads\entity_1234567890
Common Use Cases
Download Only Videos
Download Photos and Videos
Download with Size Limit
Download First 50 Files
Fast Download (10 parallel)
Understanding the Output
Download Progress
Fetching messages from entity 1234567890...
Found 125 media files to download
Downloading: 45%|█████████░░░░░░░░░░░| 56/125 [01:02<01:13, 1.11s/file]
- Progress bar - Visual download progress
- Current/Total - Files downloaded so far
- Time elapsed - How long it's been running
- Time remaining - Estimated time to completion
- Speed - Files per second
Success Message
Your files are saved in the downloads/entity_<ID> folder.
File Organization
Downloaded files are organized like this:
downloads/
├── entity_1234567890/ # Channel 1
│ ├── 12345.jpg
│ ├── 12346.mp4
│ └── 12347.pdf
├── entity_9876543210/ # Channel 2
│ ├── 98765.jpg
│ └── 98766.png
└── single_downloads/ # Individual link downloads
└── file_123.mp4
File Naming
Files are named with their message ID for reliable tracking and duplicate prevention.
Smart Features
Automatic Skip
Already downloaded files are automatically skipped:
Found 25 already downloaded files, will skip...
Fetching messages from entity 1234567890...
Found 10 new media files to download
Resume Support
If interrupted, just run the command again:
tgdl will: - ✅ Skip already downloaded files - ✅ Continue from where it stopped - ✅ Only download new media
Progress Tracking
tgdl remembers what it downloaded:
- Each entity's progress is tracked separately
- Next time you run download, only NEW messages are fetched
- Efficient for keeping media collections up-to-date
Quick Reference Card
| Task | Command |
|---|---|
| Login | tgdl login |
| Logout | tgdl logout |
| List channels | tgdl channels |
| List groups | tgdl groups |
| List bots | tgdl bots |
| Download all | tgdl download -c ID |
| Download videos | tgdl download -c ID -v |
| Download photos | tgdl download -c ID -p |
| With size limit | tgdl download -c ID --max-size 100MB |
| Fast download | tgdl download -c ID --concurrent 10 |
| Check status | tgdl status |
Keyboard Shortcuts
While downloading:
- Ctrl+C - Cancel download (can resume later)
- Progress is automatically saved
Resume Support
Automatic Resume
Interrupted downloads are automatically resumed:
# Start download
tgdl download -c 1234567890
# If interrupted with Ctrl+C:
# Files already downloaded are skipped
# Downloads continue from where it stopped
# Just run the same command again
tgdl download -c 1234567890
How It Works
- Files are named with message ID:
12345.jpg,12346.mp4 - tgdl remembers progress: Stored in
~/.tgdl/progress.json - Next run picks up automatically: Downloads new messages only
- Partial files are tracked:
.tgdl_partialfiles are excluded from dedup
First run: Download messages 1-100
✓ Completes 50 files
✗ Interrupted
→ progress.json saved
Second run: Same command
✓ Skips completed 50 files
✓ Resumes from message 51
✓ Downloads remaining files
Automatic Deduplication
Files with identical content (same hash) are automatically detected and not re-downloaded, even if interrupted and resumed.
Tips for Beginners
Start Small
For your first download, use --limit 10 to download just 10 files and see how it works.
Check Storage
Large channels can have gigabytes of media. Check available disk space first.
Use Filters
Instead of downloading everything, use filters like -v (videos only) or --max-size to save space.
Increase Speed
Default is 5 parallel downloads. For faster downloads, try --concurrent 10 or even --concurrent 20.
Next Steps
Now that you know the basics:
You're All Set!
You now know enough to start downloading media from Telegram. Explore the advanced features when you're ready!