Instagram Downloader

Instagram Downloader Skill v2.2

Purpose: Download all media (reels MP4, carousels with ALL images, photos JPG) from an Instagram profile. Three operation modes: sessionid (cookie, recommended), Apify (no login, limited), setup wizard (Playwright browser).

⚠ 2026-07-07: --login mode is BROKEN. Meta deprecated the instagrapi login endpoint server-side. The --login, --password, and --totp flags exist but return 404. Use --setup (Playwright) or a manual --sessionid cookie instead.

---

Operation Modes

graph LR
    subgraph Sessionid[Mode 1: Sessionid 🥇]
        direction TB
        S1[sessionid cookie] --> S2[login_by_sessionid]
        S2 --> S3[user_id_from_username]
        S3 --> S4[user_medias → ALL posts]
        S4 --> S5[photo_download / video_download]
        S5 --> S6[📁 YYYY-MM-DD/shortcode/]
    end
    
    subgraph Apify[Mode 2: Apify]
        direction TB
        A1[Apify Actor Dataset] --> A2[toon-file or --dataset API]
        A2 --> A3{GQL available?}
        A3 -->|Yes <4w| A4[✅ All carousel images]
        A3 -->|No >4w| A5[❌ First image only]
    end
    
    subgraph Setup[Mode 3: Setup Wizard]
        direction TB
        U1[--setup flag] --> U2[Playwright Chromium]
        U2 --> U3[User logs in]
        U3 --> U4[Extract sessionid]
        U4 --> U5[💾 Save to config.json]
    end

Mode Comparison

---

Architecture

Credential Resolution Priority

The script auto-detects credentials in this order:

1. --sessionid CLI flag — one-shot session cookie (highest priority)
2. SESSIONID environment variable — for CI/automation
3. Config file (~/.ig-downloader/config.json) — persistent, set by --setup
4. Chrome cookies — automatic extraction from browser SQLite (if logged in)

When no sessionid is found → falls to --setup (interactive) or Apify mode (if dataset provided).

⚠ The --login mode (and its settings.json persistence) is BROKEN. Meta deprecated the login endpoint. All auth must use sessionid or --setup.

Mode 1: Sessionid (Recommended)

flowchart LR
    COOKIE[sessionid cookie] --> LOGIN[login_by_sessionid]
    LOGIN --> UID[user_id_from_username]
    UID --> MEDIAS[user_mediasamount=0 → ALL posts]
    MEDIAS --> TYPE{media_type}
    TYPE -->|1: Photo| PHOTO[photo_download → .jpg]
    TYPE -->|2: Video| REEL[video_download → .mp4]
    TYPE -->|8: Carousel| CAR[media_info → resources[]]
    CAR --> IMG1[_01.jpg]
    CAR --> IMG2[_02.jpg]
    CAR --> IMGN[_0N.jpg]
    PHOTO --> DIR[📁 YYYY-MM-DD/shortcode/]
    REEL --> DIR
    IMG1 --> DIR
    DIR --> INFO[+ post_info.txt]

Mode 2: Apify (Fallback)

Same as v1.x: Apify Actor → dataset → toon file → download (with GQL carousel enhancement for recent posts).

Interactive Setup

flowchart TD
    A[Run: ig-downloader --setup] --> B{Playwright installed?}
    B -->|Yes| C[Launch Chromium browser]
    C --> D[Navigate to instagram.com]
    D --> E[User logs in]
    E --> F[Poll context.cookies every 3s]
    F --> G{sessionid detected?}
    G -->|No| F
    G -->|Yes| H[Save to config.json]
    H --> I[Close browser ✅]

    B -->|No| J{Chrome DB accessible?}
    J -->|Yes| K[DPAPI + AES-GCM decrypt]
    K --> L{File locked?}
    L -->|No| M[Extract sessionid]
    L -->|Yes| J
    M --> H

    J -->|No| N[Prompt user: paste sessionid manually]
    N --> O[Save to config.json]
    O --> I

---

Prerequisites

• Python 3.7+
• instagrapi >= 2.0.0: pip install instagrapi
• requests: pip install requests
• Chrome (optional, for interactive setup and cookie extraction)
• Apify account (free tier, only needed for Apify legacy mode)

---

Getting the Sessionid Cookie

Method A: Manual (1 minute)

1. Open Chrome, go to https://www.instagram.com
2. Log in to Instagram
3. Press F12 → Application → Cookies → www.instagram.com
4. Find sessionid — copy its value
5. Run: python instagram_downloader.py -u username --sessionid "YOUR_SESSIONID"

Method B: Interactive Setup (recommended)

python instagram_downloader.py --setup

This opens Instagram in your browser. Log in, and the script automatically detects the sessionid cookie, saves it to ~/.ig-downloader/config.json, and exits. After that, no --sessionid flag needed.

Method C: Environment Variable

set SESSIONID=YOUR_SESSIONID
python instagram_downloader.py -u username

---

Workflow

Sessionid Mode (Recommended, Full Access)

# One-time setup (Playwright browser → logs in → saves cookie)
python instagram_downloader.py --setup

# Then just download — sessionid auto-loaded from config
python instagram_downloader.py -u username -o ./downloads

# Or pass cookie directly (one-shot, no config needed)
python instagram_downloader.py -u username --sessionid "1234..." -o ./downloads

Apify Mode (No Login)

# Via MCP
await mcp_call-actor({ actor: "unseenuser/IG-posts", input: { usernames: ["username"] } })
await mcp_get-dataset-items({ datasetId: "", limit: 999, clean: true })

# Then download
python instagram_downloader.py --toon-file ./data.txt \
    -u username \
    --date-start YYYY-MM-DD --date-end YYYY-MM-DD \
    -o ./instagram_downloads

---

Script Reference

Location: instagram_downloader.py (same directory)

Command-Line Options

Mode Selection (auto-detected in order: login → sessionid → Apify → setup)

Files & Target

Filters (Apify mode only; login/sessionid modes download ALL posts)

Misc

Default Output Structure

instagram_downloads/
└── YYYY-MM-DD/
    ├── /               # Reel
    │   ├── .mp4
    │   ├── .jpg        # Thumbnail
    │   └── post_info.txt
    ├── /               # Photo
    │   ├── .jpg
    │   └── post_info.txt
    └── /               # Carousel
        ├── .jpg        # First image (cl.photo_download)
        ├── _02.jpg     # Image 2/N (from media_info)
        ├── _03.jpg     # Image 3/N
        ├── ...
        └── post_info.txt

---

Sessionid Under the Hood

Cookie Extraction

The --setup flow:

1. Opens https://www.instagram.com in the default browser via webbrowser.open()
2. Polls the Chrome cookie SQLite database every 3 seconds
3. Reads cookies using sqlite3 + DPAPI key decryption (AES-GCM with no-authentication-tag)
4. Once sessionid is detected, saves to ~/.ig-downloader/config.json
5. Closes automatically

Media Fetching

• user_id_from_username() → numeric user ID
• user_medias(user_id, amount=0) → ALL media items (amount=0 means unlimited)
• Each Media object has: pk, code (shortcode), media_type (1=photo, 2=video, 8=carousel), taken_at (datetime)
• Carousels: media_info(pk) returns carousel_media[] with all resources
• Downloads via photo_download() / video_download() with proper auth

Config Storage

{
  "sessionid": "YOUR_SESSIONID_COOKIE",
  "created_at": "2026-07-07T22:00:00"
}

Location: ~/.ig-downloader/config.json

---

Examples

Sessionid mode (from config, simplest)

# After running --setup once
python instagram_downloader.py -u username -o ./downloads

Sessionid mode (direct flag)

python instagram_downloader.py \
    -u username \
    --sessionid "1234567890%3Aabcdef" \
    -o ./downloads

Sessionid mode (environment variable)

set SESSIONID=1234567890%3Aabcdef
python instagram_downloader.py -u username -o ./downloads

Setup wizard (first time only)

python instagram_downloader.py --setup

Apify mode (toon file, with filters)

python instagram_downloader.py \
    --toon-file ./data.txt \
    -u username \
    --type reel \
    --date-start YYYY-MM-DD \
    --date-end YYYY-MM-DD \
    -o ./reels_only

Apify mode (API token)

python instagram_downloader.py \
    --dataset  \
    --api-token apify_api_xxx \
    -u username \
    -o ./downloads

---

Troubleshooting

---

Known Issues

1. Sessionid Expiration

Instagram session cookies expire after some time (days-weeks). When this happens, re-run --setup or pass a fresh --sessionid. Login mode avoids this via saved sessions + auto-reload.

2. Login Challenge Detection

Instagram may trigger a challenge (SMS/email code) on first login from a new IP. The script detects this and prompts you interactively. After the first successful login, the saved session prevents future challenges.

3. Chrome DPAPI Decryption

Cookie extraction uses Windows DPAPI + AES-GCM. Works with Chrome's latest cookie encryption (no-authentication-tag variant). If Chrome updates its format, extraction may break.

4. Private Profiles

Login/sessionid modes can only download profiles that the logged-in user follows. For private profiles you don't follow, Apify mode with unseenuser/IG-posts may work (the actor runs its own session).

5. Carousel GQL Limit (Apify mode)

GQL enhancement works only for recent posts (< 4 weeks). Older posts get single thumbnail. Login/sessionid modes avoid this entirely.

6. CDN URL Expiry (Apify mode)

Apify URLs expire after hours. Download soon after fetching. Login/sessionid modes avoid this entirely.

---

Changelog

---

Instagram Downloader Skill v2.2.0 — Sessionid + Apify + Playwright setup. Zero compromises.