Automatically monitor TikTok users and intelligently download only new videos. Features timestamp-based tracking to avoid duplicates and anti-bot behavior to appear human-like.
- 🤖 Automatic monitoring - Periodically checks for new videos
- 🎯 Smart timestamp filtering - Downloads only truly new videos (no duplicates)
- 🗄️ SQLite database - Tracks downloaded videos and metadata
- 🌍 Automatic geo-bypass - Circumvents geographical restrictions
- 🍪 Cookie support - For restricted or private videos
- ⏱️ Anti-bot delays - Randomized delays between downloads
- 🔔 Desktop notifications - Get alerted when new videos are downloaded
- 📝 Professional logging - Detailed logs with file and console output
- 🔄 Automatic retry - Handles network errors and rate limiting
- 📊 Reports & statistics - View downloads, views, likes
- 👥 Multi-user - Monitor multiple users simultaneously
- 🎨 Interactive menu - User-friendly CLI with guided options
- 📁 Organized downloads - Files named by author and date
- ⚙️ Configuration file - Customize settings with config.yaml
Even if you're not in a restricted country, using a VPN is strongly recommended:
- ✅ Better privacy - Masks your IP address from TikTok
- ✅ Avoid rate limiting - Reduces risk of temporary bans
- ✅ Consistent downloads - More stable connection to TikTok servers
- ✅ Geographic diversity - Access content from different regions
Recommended VPN locations:
- 🇺🇸 United States (best compatibility)
- 🇨🇦 Canada
- 🇩🇪 Germany
IMPORTANT
Note: Restrictions change frequently. Some videos may be unavailable in specific regions regardless of country-level restrictions.
Setup:
# 1. Connect to VPN (USA recommended)
# 2. Run the monitor
python tiktok_monitor.py --auto --users username
# The built-in geo-bypass will work better with VPN active
## 🚀 Installation
### Requirements
- Python 3.7 or higher
- pip (Python package manager)
### Quick Setup
```bash
# 1. Clone the repository
git clone https://github.com/gabrielrahbar/TikTokAutoDownloader.git
cd TikTokAutoDownloader
# 2. Install dependencies
pip install -r requirements.txt
# 3. Verify installation
python check_installation.pyIf you see this output, you're ready:
✅ EVERYTHING OK! Installation completed successfully!
The easiest way to get started:
python tiktok_monitor.pyYou'll see this menu:
╔════════════════════════════════════════════════════════════╗
║ TikTok Monitor - Main Menu v2.3 ║
╚════════════════════════════════════════════════════════════╝
👥 USER MANAGEMENT
1. ➕ Add user to monitor
2. 📋 List monitored users
3. ❌ Remove user from monitoring
...
Example workflow:
- Choose
1to add a user (e.g.,charlidamelio) - Choose
7to start automatic monitoring - The bot will check every 30 minutes [Default] (you can choose it) and download new videos
# Add users and start automatic monitoring (every 30 min)
python tiktok_monitor.py --auto --interval 30 --users charlidamelio khaby.lame
# Check once only (no loop)
python tiktok_monitor.py --check-once --users charlidamelio
# Show statistics
python tiktok_monitor.py --statsTo download a single video:
# Basic download
python tiktok_downloader_advanced.py https://www.tiktok.com/@user/video/123456789
# With cookies (for geo-restrictions)
python tiktok_downloader_advanced.py --cookies tiktok_cookies.txt URL
# Show cookie export instructions
python tiktok_downloader_advanced.py --help-cookiesQuick script to manage users without interactive menu:
# List all monitored users
python manage_users.py --list
# Add new user
python manage_users.py --add username
# Remove user (disable)
python manage_users.py --remove username
# Permanently delete (with confirmation)
python manage_users.py --delete username
# Re-enable disabled user
python manage_users.py --enable usernameCustomizable settings using a config.yaml file in the project root.
monitor:
interval_minutes: 30
output_dir: "./tiktok_downloads"
download:
quality: "best"
geo_bypass: true
notifications:
enabled: falseView detailed download report:
python view_report.pyExample output:
╔════════════════════════════════════════════════════════════╗
║ TikTok Monitor Report ║
╚════════════════════════════════════════════════════════════╝
📊 GENERAL STATISTICS
────────────────────────────────────────────────────────────
Downloaded videos: 142
Total views: 1,245,890
Total likes: 89,234
👥 BY AUTHOR
────────────────────────────────────────────────────────────
@charlidamelio 45 videos | 890,234 views | 67,123 likes
@khaby.lame 38 videos | 234,567 views | 12,345 likes
...
If you get errors like "Video not available in your country":
-
Install "Get cookies.txt LOCALLY" extension
-
Go to tiktok.com and login
-
Click extension icon →
Export -
Save as
tiktok_cookies.txt -
Use cookies:
python tiktok_downloader_advanced.py --cookies tiktok_cookies.txt URL
Connect to a VPN (USA/UK) before running downloads. The automatic geo-bypass will handle the rest.
TikTokAutoDownloader/
├── tiktok_monitor.py # 🤖 Main monitor with interactive menu
├── tiktok_downloader_advanced.py # 📥 Standalone downloader
├── manage_users.py # 👥 CLI user management
├── view_report.py # 📊 Reports and statistics
├── check_installation.py # ✅ Installation verification
├── requirements.txt # 📦 Python dependencies
├── README.md # 📖 This guide
├── LICENSE # ⚖️ MIT License
├── .gitignore # 🚫 Files to ignore
├── tiktok_downloads/ # 📁 Downloaded videos (auto-created)
└── tiktok_monitor.db # 🗄️ SQLite database (auto-created)
The monitor uses an intelligent timestamp-based system:
- First run: Saves the timestamp of the most recent video
- Subsequent checks: Downloads only videos with timestamp > last saved
- Anti-duplicates: Also checks database for safety
- Update: Always saves the timestamp of the newest downloaded video
This prevents the "false new videos" problem that other scrapers have.
To avoid TikTok bans:
- ⏱️ Randomized delays between downloads (5-15 seconds)
- 🎲 Delays between different users (10-30 seconds)
- 🌐 User-Agent rotation
- 📅 Variable check intervals (±10%)
The SQLite database tracks:
- videos: id, url, title, author, timestamp, likes, views, file_path
- monitored_users: username, last_check, last_video_timestamp, total_videos
pip install --upgrade yt-dlpUse cookies (see Cookies section above) or connect to a VPN.
Close all monitor instances before restarting:
# Linux/Mac
pkill -f tiktok_monitor.py
# Windows (Task Manager)
Search "python" and close the processesIncrease timeout by modifying yt-dlp options in code or use a more stable connection.
The bot is going too fast. Increase delays in tiktok_monitor.py:
# Around line ~300
delay = random.uniform(10, 20) # Increase these valuespython check_installation.pyContributions are welcome!
- Fork the project
- Create a branch (
git checkout -b feature/AmazingFeature) - Commit your changes (
git commit -m 'Add AmazingFeature') - Push to the branch (
git push origin feature/AmazingFeature) - Open a Pull Request
See CONTRIBUTING.md for details.
For personal and educational use only.
- ⚖️ Respect TikTok's Terms of Service
- 📝 Video rights belong to their respective authors
- 🚫 Do not use to redistribute content without permission
⚠️ The author is not responsible for misuse of this software
- 🎯 User-friendly error handling with clear solutions
- 📋 ConfigManager for YAML-based configuration
- 🔔 Desktop notifications for new downloads
- 📊 Professional logging system with daily rotation
- 🔄 Smart retry logic based on error type
- ✅ Integration tests for TikTok API
- 🧪 Comprehensive unit tests
- ✨ Added timestamp-based filtering (no more duplicates)
- 🎯 Limited check to last 5 videos per user
- 🛠️ Improved anti-bot with randomized delays
- 📊 Added
view_report.pyfor statistics - 👥 Added
manage_users.pyfor CLI - ✅ Added
check_installation.py
- 🎉 Initial release
- 🤖 Basic automatic monitoring
- 📥 Download with geo-bypass
Author: gabrielrahbar
- GitHub: @gabrielrahbar
- Issues: Report a problem
This project is released under the MIT License. See the LICENSE file for details.
⭐ If this project is useful to you, leave a star on GitHub! ⭐
Made with ❤️ by gabrielrahbar