ind4skylivey/IG-saver-tools

Features • Quick Start • Demo • Usage • Roadmap • Contributing

🎯 Why IGsaver?

❌ The Problem 📉 48+ hours waiting for Instagram export ⏰ Stories disappear in 24h forever 🔒 Memories locked in Instagram servers 💔 Account issues = Lost content

✅ The Solution ⚡ Instant backup, any time 🎯 Capture stories before expiration 💾 Store locally on YOUR device 🛡️ Full control of your data

./run.sh              # That's it! All your highlights backed up locally in seconds ⚡

✨ Features

🚀 Smart & Fast Performance: ⚡ Incremental Backup: Skip existing files 📊 90% faster on subsequent runs 🎯 Batch Download: All at once ⏱️ Stories: Before 24h expiration	🔐 Safe & Secure Security: 🔒 Zero password storage 🛡️ 2FA Support built-in 💾 100% Local storage 📖 Open Source code
⚙️ Powerful & Flexible Customization: 📝 YAML Configuration files 🔍 Advanced Filters (date/type/size) 💻 CLI with 15+ options 📈 Detailed reports & stats	🎯 Coming Soon v2.0.0 Roadmap: 🖥️ Desktop App (Win/Mac/Linux) 📅 Scheduled Auto-backups ☁️ Optional Cloud Sync 📊 Analytics Dashboard

📦 Demo & Output

Note: Live screenshots and demo GIF coming soon! The tool is fully functional and tested.

📁 backups/
└── 📱 your_username/
    ├── 📸 highlights/
    │   ├── 🌍 Travel_2024/
    │   │   ├── 🎬 2024-01-20_01-56-19_UTC.mp4   (15.2 MB)
    │   │   ├── 🎬 2024-02-05_13-27-04_UTC.mp4   (23.8 MB)
    │   │   ├── 📷 2024-03-10_08-15-30_UTC.jpg   (2.1 MB)
    │   │   └── 📝 metadata.json
    │   ├── ❤️ Family_Moments/
    │   │   └── 💫 25 items backed up
    │   └── ⭐ Best_Memories/
    │       └── 💫 18 items backed up
    └── 🎪 stories/ (if --stories flag used)
        └── 💫 Active stories (before 24h expiration)

$ ./run.sh

==================================================
Instagram Highlights Backup Tool
==================================================
Loading saved session for your_username...
✓ Session loaded successfully

Processing highlights: 100%|████████████| 15/15 [02:30<00:00]

📁 Travel 2024
  ✓ 12 items, 0 failed

📁 Family Moments
  ✓ 25 items, 1 failed

============================================================
BACKUP SUMMARY
============================================================
Target: your_username
Duration: 2m 35s

Highlights:
  ✓ Downloaded: 15
  ⊘ Skipped: 0
  ━ Total found: 15

Items:
  ✓ Downloaded: 134
  ⊘ Skipped (already exist): 0
  ━ Total: 134

Downloaded: 2.1 GB

✓ BACKUP COMPLETED SUCCESSFULLY
============================================================

🚀 Quick Start

1. Create virtual environment (optional but recommended):

python3 -m venv venv
source venv/bin/activate

2. Install dependencies:

pip install -r requirements.txt

3. (Optional) Configure username:

cp .env.example .env
# Edit .env with your Instagram username (optional)

Usage

Basic Usage

Download your highlights (with incremental backup):

./run.sh

Download active stories (24h):

./run.sh --stories

Download from another user:

./run.sh username

Force re-download everything:

./run.sh --force

Advanced Options

# Custom output directory
./run.sh -o /backup/location

# Quiet mode (minimal output)
./run.sh -q

# Verbose mode (debug info)
./run.sh -v

# Disable progress bars
./run.sh --no-progress

# See all options
./run.sh --help

Configuration File (Optional)

Create config.yaml to customize behavior:

download:
  only_videos: false      # Download only videos
  only_photos: false      # Download only photos
  min_date: 2024-01-01    # Download from this date
  max_date: null          # Download until this date

filters:
  exclude_patterns: []    # Skip items matching patterns
  min_size_mb: null       # Minimum file size

See config.example.yaml for all options.

Project Structure

IGsaver/
├── src/
│   ├── main.py           # Entry point
│   ├── app.py            # Main application orchestrator
│   ├── auth.py           # Authentication & session management
│   ├── downloader.py     # Download logic
│   ├── config.py         # Configuration management
│   ├── logger.py         # Logging setup
│   ├── ui.py             # User interface & output
│   ├── exceptions.py     # Custom exceptions
│   └── constants.py      # Constants and configuration
├── igsaver.py            # Convenience entry point
├── backups/              # Downloaded backups stored here
├── .sessions/            # Session tokens (excluded from git)
├── logs/                 # Process logs
├── requirements.txt      # Python dependencies
├── .env                  # Credentials (not included in git)
└── .env.example          # Configuration example

Architecture

The project follows Clean Code principles:

• Separation of Concerns: Each module has a single responsibility
• Type Hints: All functions are properly typed
• Dependency Injection: Components receive dependencies
• Custom Exceptions: Proper error handling with specific exceptions
• Logging: Comprehensive logging for debugging and monitoring
• UI Separation: Business logic separated from presentation

Security

3-Layer Authentication System:

1. Session Tokens (primary method)

   • First time: Login with password
   • Instaloader saves a session token in .sessions/
   • Subsequent uses: Token is used automatically

2. Interactive Prompt (fallback)

   • If no session exists or expired
   • Asks for password securely using getpass
   • Password is never displayed or saved

3. Zero Password Storage

   • ✅ Encrypted session tokens (renewable)
   • ✅ Passwords only in temporary memory
   • ❌ Passwords are NEVER saved to files

Other considerations:

• If you have 2FA enabled, consider disabling it temporarily
• Instagram may rate-limit requests if you download too much at once
• Session tokens are stored in .sessions/ (excluded from git)

🗺️ Roadmap

See our complete ROADMAP.md for detailed plans!

Current Status: v1.0.0 ✅

• Advanced CLI with 15+ options
• Smart incremental backup (90% faster!)
• Download highlights & stories (24h)
• Visual progress bars
• Comprehensive reports
• YAML configuration
• 2FA support

Coming in v2.0.0 🚀

• 🖥️ Desktop App (Windows, Mac, Linux)
• 📅 Scheduled Backups (Automatic daily sync)
• ☁️ Cloud Sync (Optional backup to cloud)
• 📊 Analytics Dashboard (Visualize your content)
• 🎨 Modern GUI (Dark/Light themes)
• 🔔 Notifications (Desktop alerts)

View Full Roadmap →

🤝 Contributing

We love contributions! Whether it's:

• 🐛 Bug reports
• 💡 Feature requests
• 📖 Documentation improvements
• 🔧 Code contributions
• 🎨 UI/UX design for desktop app

Check out CONTRIBUTING.md to get started!

Special call: We're planning a desktop app! If you have experience with Electron, Tauri, or PyQt, we'd love your input via Issues.

⭐ Show Your Support

If IGsaver helped you backup your precious memories:

• ⭐ Star this repo to show your support
• 🐦 Share on social media to help others discover it
• 🔗 Tell your friends who might need it
• 🤝 Contribute to make it even better

📄 License

MIT License - feel free to use, modify, and distribute!

See LICENSE for full details.

🙏 Acknowledgments

Built with:

• Instaloader - Instagram API wrapper
• tqdm - Progress bars
• Love for preserving memories ❤️

Made with ❤️ by @il1v3y

For Instagram users who want to own their memories

⭐ Star this repo if it helped you!

📧 Questions? Open an issue and we'll help you!

_{Built with Python 🐍 | Powered by Instaloader 📸 | Designed for Privacy 🔒}