instaloader-gui-wrapper

KO | EN

gitlite — search

#ai-agents #typescript #ai #dsh-plugin #deepseek-harness #cli #open-source #codex #ios #claude-code #developer-tools #python

instaloader-gui-wrapper

★ 28 Open GitHub ↗

A desktop application that provides a user-friendly graphical interface for downloading content from Instagram profiles using the Instaloader Python library.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Instaloader GUI Wrapper

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PyQt6](https://img.shields.io/badge/GUI-PyQt6-green.svg)](https://pypi.org/project/PyQt6/)
</div>

A desktop application that provides a user-friendly graphical interface for downloading content from Instagram profiles using the [Instaloader](https://instaloader.github.io/) Python library.

![Screenshot](https://raw.githubusercontent.com/marhensa/instaloader-gui-wrapper/main/assets/screenshot-a.jpg)

![Screenshot](https://raw.githubusercontent.com/marhensa/instaloader-gui-wrapper/main/assets/screenshot-b.jpg)

## ☕ Support

If you find this tool useful, consider supporting development:

[![Ko-fi](https://img.shields.io/badge/Ko--fi-Support%20Me-ff5f5f?logo=ko-fi)](https://ko-fi.com/marhensa)

## Features

- **Profile Downloads** - Posts, stories, highlights, and profile pictures
- **Saved Posts** - Download your own saved posts collection with flexible organization
- **Single Content** - Download individual posts, reels, stories, or highlights via URL
- **Anti-Detection** - Highly configurable "Balanced" timing system to mimic human behavior
- **2FA Support** - Full two-factor authentication support
- **Unified Progress** - Overall progress bar for all download modes
- **Enhanced Stop** - Immediate cancellation responsiveness during stays and retries
- **Date Filtering** - Download content within specific date ranges
- **Live Preview** - See downloaded content in real-time
- **Dark Theme** - Modern PyQt6 dark-themed interface

## Quick Start

### Option 1: Run from Source

```bash
# Clone the repository
git clone https://github.com/marhensa/instaloader-gui-wrapper.git
cd instaloader-gui-wrapper

# Install dependencies
pip install -r requirements.txt

# Run the application
python run.py
```

### Option 2: Windows & Linux Executables

Download the latest release from [Releases](https://github.com/marhensa/instaloader-gui-wrapper/releases) and run the executable for your platform.

## Usage

1. **Login** - Enter credentials or use a session file
2. **Choose Mode** - Select between **Target Profile**, **Saved Posts**, or **Single Content**
3. **Set Parameters** - Enter the target username or URL, and configure filters like date ranges, stories, or highlights
4. **Set Location** - Choose the download directory
5. **Start** - Click ▶ Start to begin the download process

### Supported URL Formats

| Type | Example URL |
|------|-------------|
| Profile | `instagram.com/username` |
| Post | `instagram.com/p/ABC123` |
| Reel | `instagram.com/reel/ABC123` |
| Story | `instagram.com/stories/username/123456` |
| Highlight | `instagram.com/stories/highlights/123456` |

### Download Structure

**Standard Downloads (Target Profile and Single Post):**
```
downloads/
└── username/
    ├── profile_pic/
    ├── posts/
    ├── stories/
    └── highlights/
```

**Saved Posts Downloads (Default):**
```
downloads/
└── saved_posts/
    ├── username1/
    │   ├── 2024-01-01_UTC.jpg
    │   └── ...
    └── username2/
        └── ...
```

**Saved Posts Downloads (Single Folder):**
```
downloads/
└── saved_posts/
    ├── username1_2024-01-01_UTC.jpg
    ├── username2_2024-01-02_UTC.jpg
    └── ...
```

## Advanced Settings

| Setting | Description | Default |
|---------|-------------|---------|
| Base Delay | Baseline time between requests | 3s |
| Random Jitter | Extra random time to appear human | 2s |
| Story Multiplier | Safety multiplier for stories/highlights | 1.5x |
| Long Pause | Range for random "session" breaks | 10-17s |
| Critical Wait | Recovery time after rate limits | 30min |

## Security

- Credentials are never stored in plain text
- Session files location:
  - Windows: `%localappdata%\Instaloader\session-username`
  - Linux/Mac: `~/.config/instaloader/session-username`
- **Delete session files on shared computers!**

## Building from Source

### Windows
```bash
build.bat
# Output: dist/Instaloader-GUI-Wrapper.exe
```

### Linux

**Requirements**: `python3`, `pip`, `binutils`, `fuse-libs`, `file`

```bash
# Install dependencies (Ubuntu/Debian)
sudo apt update && sudo apt install -y python3 python3-pip binutils libfuse2 file

# Install dependencies (Fedora/RHEL)
sudo dnf install -y python3 binutils fuse-libs file

# Build
chmod +x build.sh
./build.sh
```

This will produce:
- `dist/Instaloader-GUI-Wrapper` (Executable)
- `Instaloader-GUI-Wrapper-x86_64.AppImage` (Portable AppImage)

### Manual Build
```bash
pip install pyinstaller
pyinstaller --onefile --windowed --name "Instaloader-GUI-Wrapper" run.py
```

## Project Structure

```
instaloader-gui-wrapper/
├── run.py              # Entry point
├── requirements.txt    # Dependencies
├── build.bat           # Build script
├── build.sh            # Build script
├── downloads/          # Downloaded content
├── user-settings/      # User settings
└── src/
    ├── gui/            # UI components
    ├── core/           # Download logic
    └── config/         # Settings
```

## ⚠️ Disclaimer

This tool is for **personal use only**. Respect Instagram's terms of service and copyright rules. Excessive downloads may trigger rate limiting. The developer is not responsible for misuse.

## License

instaloader-gui-wrapper

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README