{"id":35183799,"url":"https://github.com/kavidu-dilhara/tgdl","last_synced_at":"2026-04-05T11:31:34.309Z","repository":{"id":323640999,"uuid":"1094151038","full_name":"kavidu-dilhara/tgdl","owner":"kavidu-dilhara","description":"A high-performance CLI tool for downloading media from Telegram","archived":false,"fork":false,"pushed_at":"2026-03-19T12:20:59.000Z","size":950,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-20T05:16:35.795Z","etag":null,"topics":["bulk-download","telegram-media-downloader","telegram-scraper","tgdl"],"latest_commit_sha":null,"homepage":"https://kavidu-dilhara.github.io/tgdl/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kavidu-dilhara.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/contributing.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-11T10:23:36.000Z","updated_at":"2026-03-19T12:22:07.000Z","dependencies_parsed_at":"2025-11-11T10:55:53.524Z","dependency_job_id":null,"html_url":"https://github.com/kavidu-dilhara/tgdl","commit_stats":null,"previous_names":["kavidu-dilhara/tgdl"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/kavidu-dilhara/tgdl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kavidu-dilhara%2Ftgdl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kavidu-dilhara%2Ftgdl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kavidu-dilhara%2Ftgdl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kavidu-dilhara%2Ftgdl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kavidu-dilhara","download_url":"https://codeload.github.com/kavidu-dilhara/tgdl/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kavidu-dilhara%2Ftgdl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31434624,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T08:13:15.228Z","status":"ssl_error","status_checked_at":"2026-04-05T08:13:11.839Z","response_time":75,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bulk-download","telegram-media-downloader","telegram-scraper","tgdl"],"created_at":"2025-12-29T04:27:16.693Z","updated_at":"2026-04-05T11:31:34.301Z","avatar_url":"https://github.com/kavidu-dilhara.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🚀 Telegram Media Downloader - tgdl\n\n\u003cdiv align=\"center\"\u003e\n  \u003cp\u003e\n    \n![GitHub Repo stars](https://img.shields.io/github/stars/kavidu-dilhara/tgdl)\n![GitHub watchers](https://img.shields.io/github/watchers/kavidu-dilhara/tgdl)\n![GitHub forks](https://img.shields.io/github/forks/kavidu-dilhara/tgdl)\n![GitHub License](https://img.shields.io/github/license/kavidu-dilhara/tgdl)\n![PyPI - Downloads](https://img.shields.io/pypi/dm/tgdl)\n![PyPI - Format](https://img.shields.io/pypi/format/tgdl)\n![PyPI - Status](https://img.shields.io/pypi/status/tgdl)\n[![PyPI version](https://badge.fury.io/py/tgdl.svg)](https://badge.fury.io/py/tgdl)\n[![Python versions](https://img.shields.io/pypi/pyversions/tgdl.svg)](https://pypi.org/project/tgdl/)\n\n\n  \u003c/p\u003e\n\u003c/div\u003e\n\nA powerful, high-performance CLI tool for downloading media from Telegram channels, groups, bot chats, and messages. Built with async/await for **5-10x faster** downloads with smart filters and progress tracking.\n\n\n## ✨ Features\n\n- ⚡ **Blazing Fast** - Parallel async downloads (5-10x faster than traditional tools)\n- 🎯 **Smart Filters** - Download by media type (photos, videos, audio, documents)\n- 📏 **Size Control** - Filter by file size (min/max)\n- 🔄 **Auto-Resume** - Automatically skips already downloaded files\n- 📊 **Progress Bars** - Real-time progress with download statistics\n- 💾 **Session Management** - Secure login with saved sessions\n- 🛡️ **Error Handling** - Graceful error recovery and interruption handling\n- ⚙️ **Configurable** - Customize parallel downloads and output directories\n- 🎨 **User-Friendly** - Beautiful CLI interface with colors and emojis\n\n## 📦 Installation\n\n### From PyPI (Recommended)\n\n```bash\npip install tgdl\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/kavidu-dilhara/tgdl.git\ncd tgdl\npip install -e .\n```\n\n\n## 🚀 Quick Start\n\n### 1. Get API Credentials\n\nGet your Telegram API credentials from [https://my.telegram.org/apps](https://my.telegram.org/apps)\n\n### 2. Login\n\n```bash\ntgdl login\n```\n\nEnter your API ID, API Hash, and phone number when prompted.\n\n### 3. List Your Channels/Groups/Bots\n\n```bash\n# List all channels\ntgdl channels\n\n# List all groups\ntgdl groups\n\n# List all bot chats\ntgdl bots\n```\n\n### 4. Download Media\n\n```bash\n# Download all media from a channel\ntgdl download -c CHANNEL_ID\n\n# Download only photos and videos\ntgdl download -c CHANNEL_ID -p -v\n\n# Download from a bot chat\ntgdl download -b BOT_ID -d\n\n# Download with file size limit\ntgdl download -g GROUP_ID --max-size 100MB\n\n# Download from a message link\ntgdl download-link https://t.me/channel/123\n```\n\n## 📖 Usage\n\n### Commands\n\n#### `tgdl login`\nLogin to Telegram and save session.\n\n```bash\ntgdl login\n```\n\n#### `tgdl channels`\nList all channels you're a member of.\n\n```bash\ntgdl channels\n```\n\n#### `tgdl groups`\nList all groups you're a member of.\n\n```bash\ntgdl groups\n```\n\n#### `tgdl bots`\nList all bot chats.\n\n```bash\ntgdl bots\n```\n\n#### `tgdl download`\nDownload media from a channel, group, or bot chat with filters.\n\n```bash\ntgdl download [OPTIONS]\n\nOptions:\n  -c, --channel INTEGER       Channel ID to download from\n  -g, --group INTEGER         Group ID to download from\n  -b, --bot INTEGER           Bot chat ID to download from\n  -p, --photos               Download only photos\n  -v, --videos               Download only videos\n  -a, --audio                Download only audio files\n  -d, --documents            Download only documents\n  --max-size TEXT            Maximum file size (e.g., 100MB, 1GB)\n  --min-size TEXT            Minimum file size (e.g., 1MB, 10KB)\n  --limit INTEGER            Maximum number of files to download\n  --concurrent INTEGER       Number of parallel downloads (default: 5)\n  -o, --output TEXT          Output directory (default: downloads)\n  -h, --help                 Show this message and exit\n```\n\n#### `tgdl download-link`\nDownload media from a single message link.\n\n```bash\ntgdl download-link LINK [OPTIONS]\n\nOptions:\n  -p, --photos               Accept only photos\n  -v, --videos               Accept only videos\n  -a, --audio                Accept only audio files\n  -d, --documents            Accept only documents\n  --max-size TEXT            Maximum file size\n  --min-size TEXT            Minimum file size\n  -o, --output TEXT          Output directory\n  -h, --help                 Show this message and exit\n```\n\n#### `tgdl status`\nCheck authentication status and configuration.\n\n```bash\ntgdl status\n```\n\nShows:\n- Authentication status\n- User information (name, ID, username)\n- Config file locations\n- API credentials (masked)\n\n#### `tgdl logout`\nLogout from Telegram and remove session.\n\n```bash\ntgdl logout\n```\n\nThis will:\n- Remove your local session file\n- Delete stored API credentials\n- Optionally clear download progress\n\n#### `tgdl --version`\nShow version information.\n\n```bash\ntgdl --version\n```\n\n\n## 📁 File Organization\n\nDownloaded files are organized as follows:\n\n```\ndownloads/\n├── entity_1234567890/          # Channel/Group ID\n│   ├── file1.jpg\n│   ├── file2.mp4\n│   └── ...\n└── single_downloads/            # Files from download-link\n    ├── video.mp4\n    └── ...\n```\n\n## ⚙️ Configuration\n\nConfiguration is stored in `~/.tgdl/`:\n\n- `config.json` - API credentials and settings\n- `tgdl.session` - Telegram session (encrypted)\n- `progress.json` - Download progress tracker\n\n## 🎯 Requirements\n\n- Python 3.7 or higher\n- Active Telegram account\n- Telegram API credentials (API ID \u0026 API Hash from [https://my.telegram.org/apps](https://my.telegram.org/apps))\n\n## 🚀 Performance\n\n- **5-10x faster** than traditional downloaders\n- **Parallel downloads** with configurable concurrency\n- **Smart caching** - skips already downloaded files\n- **Optimized I/O** - async operations throughout\n\n### Benchmarks\n\n| Files | Sequential | tgdl | Speed Up |\n|-------|-----------|------|----------|\n| 10    | ~5 min    | ~1 min | 5x |\n| 100   | ~45 min   | ~8 min | 5.6x |\n| 1000  | ~7.5 hrs  | ~1.3 hrs | 5.8x |\n\n*Results vary based on internet speed and file sizes*\n\n## 🛠️ Troubleshooting\n\n### Rate Limiting\nIf you get rate limited by Telegram, reduce concurrency:\n```bash\ntgdl download -c CHANNEL_ID --concurrent 2\n```\n\n### Authentication Issues\nIf you have authentication problems:\n```bash\n# Check status\ntgdl status\n\n# Login again\ntgdl login\n```\n\n### Session Expired\nDelete session and login again:\n```bash\n# On Linux/Mac\nrm ~/.tgdl/tgdl.session\n\n# On Windows\ndel %USERPROFILE%\\.tgdl\\tgdl.session\n\n# Then login\ntgdl login\n```\n\n## 🎨 Screenshots\n\n```\n$ tgdl download -c 1234567890 -p -v\n\n📥 Download Settings\n  Entity: Channel 1234567890\n  Media types: photo, video\n  Parallel downloads: 5\n  Output: downloads\n\nFound 123 already downloaded files, skipping...\nFetching messages from entity 1234567890...\nFound 45 media files to download\n\nDownloading: 100%|████████████████| 45/45 [02:15\u003c00:00, 3.33file/s]\n\n✓ Successfully downloaded 45 files!\nFiles saved to: downloads/entity_1234567890\n\n🎉 Download complete! 45 files downloaded.\n```\n\n## � Advanced Usage\n\n### Media Type Filters\n\nCombine multiple media type filters:\n```bash\n# Photos and videos only\ntgdl download -c 1234567890 -p -v\n\n# Only documents\ntgdl download -c 1234567890 -d\n\n# Only audio files\ntgdl download -c 1234567890 -a\n```\n\n### File Size Filters\n\nControl file sizes:\n```bash\n# Download files between 1MB and 100MB\ntgdl download -c 1234567890 --min-size 1MB --max-size 100MB\n\n# Only large files (\u003e50MB)\ntgdl download -c 1234567890 --min-size 50MB\n\n# Only small files (\u003c10MB)\ntgdl download -c 1234567890 --max-size 10MB\n```\n\n### Limit Number of Files\n\n```bash\n# Download only first 10 files\ntgdl download -c 1234567890 --limit 10\n\n# Download first 100 videos\ntgdl download -c 1234567890 -v --limit 100\n```\n\n### Custom Output Directory\n\n```bash\n# Save to custom directory\ntgdl download -c 1234567890 -o /path/to/downloads\n\n# Use relative path\ntgdl download -c 1234567890 -o ./my_downloads\n```\n\n### Performance Tuning\n\n```bash\n# Slow but safe (good for rate limits)\ntgdl download -c 1234567890 --concurrent 2\n\n# Balanced (default)\ntgdl download -c 1234567890 --concurrent 5\n\n# Fast (if you have good internet)\ntgdl download -c 1234567890 --concurrent 10\n```\n\n## 🔐 Security \u0026 Privacy\n\n- API credentials stored securely in `~/.tgdl/config.json`\n- Session file encrypted by Telethon\n- No data sent to third parties\n- All downloads happen directly from Telegram servers\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## ⚠️ Disclaimer\n\nThis tool is for personal use only. Please respect:\n- Telegram's Terms of Service\n- Copyright laws\n- Content creators' rights\n- Rate limits and server resources\n\n## 🔗 Links\n\n- [📚 Documentation](https://kavidu-dilhara.github.io/tgdl/) - Complete guide and API reference\n- [PyPI Package](https://pypi.org/project/tgdl/)\n- [GitHub Repository](https://github.com/kavidu-dilhara/tgdl)\n- [Issue Tracker](https://github.com/kavidu-dilhara/tgdl/issues)\n- [Telegram API Documentation](https://core.telegram.org/api)\n- [Telethon Documentation](https://docs.telethon.dev/)\n\n## 💬 Support\n\nIf you have questions or need help:\n- Open an issue on [GitHub](https://github.com/kavidu-dilhara/tgdl/issues)\n- Check existing issues for solutions\n\n---\n\n**Made with ❤️ by kavidu-dilhara**\n\n**Happy Downloading! 🎉**\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkavidu-dilhara%2Ftgdl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkavidu-dilhara%2Ftgdl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkavidu-dilhara%2Ftgdl/lists"}