instagram-dl 0.1.0

Async Instagram downloader CLI — profiles, posts, reels, stories, highlights, hashtags, comments. Pluggable backends (HikerAPI / aiograpi).

insta-dl

Async command-line downloader for Instagram. Profiles, posts, reels, stories, highlights, hashtags, and comments — saved to disk with the original timestamps preserved.

pip install instagram-dl           # pip
pipx install instagram-dl          # or as an isolated CLI app

export HIKERAPI_TOKEN=your_token
insta-dl instagram

Or run it without installing Python at all:

docker run --rm -v "$PWD/out:/data" -e HIKERAPI_TOKEN \
    ghcr.io/subzeroid/insta-dl:latest instagram

Grab a free HikerAPI token at hikerapi.com — first 100 requests are free, no credit card. One request ≈ one post or one page of a feed.

insta-dl

• downloads profiles, hashtags, single posts, reels, stories, highlights, and comments,
• preserves the original taken_at timestamp as file mtime so Photos/Finder sort correctly,
• writes a JSON metadata sidecar next to every post (caption, like count, location, owner),
• supports incremental updates with --fast-update and --latest-stamps,
• accepts profile names, #hashtag, post shortcodes, and full instagram.com URLs,
• ships two pluggable backends: a paid commercial API (HikerAPI, no Instagram session, no ban risk) out of the box, and an opt-in private-API library via pip install 'instagram-dl[aiograpi]' (your own login).

insta-dl [--backend hiker|aiograpi]
         [--dest DIR] [--fast-update] [--latest-stamps FILE]
         [--stories] [--highlights] [--comments]
         profile | "#hashtag" | post:SHORTCODE | https://instagram.com/...

📖 Full documentation — installation, CLI reference, backends comparison, Python API, troubleshooting.

How to download an Instagram profile

export HIKERAPI_TOKEN=$(cat ~/.config/hikerapi-token)
insta-dl --dest ./out instagram

This grabs every post, names files 2026-04-21_16-04-15_DXZlTiKEpxw.mp4, and writes a metadata sidecar next to each.

How to keep a local archive in sync

insta-dl --fast-update --latest-stamps ./stamps.ini --dest ./out instagram

--fast-update stops at the first post that's already on disk; --latest-stamps records the newest taken_at per profile so even a deleted local copy can be resumed.

How to download a single post or reel

insta-dl post:DXZlTiKEpxw
insta-dl https://www.instagram.com/p/DXZlTiKEpxw/
insta-dl https://www.instagram.com/reel/DXZlTiKEpxw/

How to download a hashtag

insta-dl '#sunset' --dest ./out

Pulls the recent feed for the tag into ./out/#sunset/.

How to grab stories and highlights

insta-dl --stories --highlights --dest ./out instagram

Stories and highlights land under <dest>/<username>/stories/ and <dest>/<username>/highlights/<id>_<title>/.

How to save comments alongside posts

insta-dl --comments --dest ./out instagram

Each post gets a ..._comments.json sidecar streamed to disk.

Backends

Pick the one that matches how you want to authenticate.

	hiker (default)	aiograpi (in development)
Auth	API token	Instagram login + 2FA
Cost	Paid per request, 100 free requests to start	Free
Account ban risk	None — no Instagram session involved	Real, mitigated by session reuse
Stability vs. Instagram changes	High (managed proxy)	Brittle
Private profiles	What HikerAPI exposes	Anything your account can see

Switch with --backend:

insta-dl --backend hiker --hiker-token TOKEN instagram
pip install 'instagram-dl[aiograpi]'   # aiograpi's deps are opt-in
insta-dl --backend aiograpi --login USER --password PASS --session ./session.json instagram

Detailed comparison and auth setup: see the backends documentation. For how insta-dl stacks up against instaloader, yt-dlp, and gallery-dl, see compared to alternatives.

Output layout

<dest>/<username>/
    2026-04-21_16-04-15_DXZlTiKEpxw.mp4
    2026-04-21_16-04-15_DXZlTiKEpxw.json           # metadata sidecar
    2026-04-21_16-04-15_DXZlTiKEpxw_comments.json  # with --comments
    stories/
        2026-04-21_18-30-00_178290.jpg             # with --stories
    highlights/
        17991_Travel/                              # with --highlights
            2025-10-12_19-20-30_4011.jpg

Hashtag downloads land under <dest>/#<tag>/; single-post downloads use the post owner's username (or owner_pk fallback).

Status

This is alpha. The hiker backend is functional end-to-end (197 tests, 95% coverage). The aiograpi backend is stubbed pending an upstream sync. CLI flags and output layout are stable; Python API may still shift.

What's not yet implemented:

• private profiles requiring login (waiting on aiograpi)
• :feed and :saved (account-bound, blocked on aiograpi)
• post-filter expressions (planned: AST-restricted eval)
• automatic retry/backoff on 429/5xx

See the changelog for what landed when, and contributing for how to help.

Contributing

Bug reports, fixes, and backend implementations welcome. Start with CONTRIBUTING.md. Tests: pip install -e .[dev] && pytest.

Disclaimer

insta-dl is not affiliated with, authorized, maintained, or endorsed by Instagram or Meta. Use at your own risk and respect the rights of content creators. Licensed under MIT.