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 instagramOr run it without installing Python at all:
docker run --rm -v "$PWD/out:/data" -e HIKERAPI_TOKEN \
ghcr.io/subzeroid/insta-dl:latest instagramGrab 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_attimestamp 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-updateand--latest-stamps, - accepts profile names,
#hashtag, post shortcodes, and fullinstagram.comURLs, - 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.
export HIKERAPI_TOKEN=$(cat ~/.config/hikerapi-token)
insta-dl --dest ./out instagramThis grabs every post, names files 2026-04-21_16-04-15_DXZlTiKEpxw.mp4, and writes a metadata sidecar next to each.
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.
insta-dl post:DXZlTiKEpxw
insta-dl https://www.instagram.com/p/DXZlTiKEpxw/
insta-dl https://www.instagram.com/reel/DXZlTiKEpxw/insta-dl '#sunset' --dest ./outPulls the recent feed for the tag into ./out/#sunset/.
insta-dl --stories --highlights --dest ./out instagramStories and highlights land under <dest>/<username>/stories/ and <dest>/<username>/highlights/<id>_<title>/.
insta-dl --comments --dest ./out instagramEach post gets a ..._comments.json sidecar streamed to disk.
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 instagramDetailed 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.
<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).
This is alpha. The hiker backend is functional end-to-end (224 tests, 95% coverage). The aiograpi backend is stubbed pending an upstream sync (and ships behind the [aiograpi] extra so its Rust deps don't bloat default installs). CLI flags and output layout are stable; Python API may still shift.
What's not yet implemented:
- private profiles requiring login (waiting on aiograpi)
:feedand:saved(account-bound, blocked on aiograpi)
See the changelog for what landed when, and contributing for how to help.
Bug reports, fixes, and backend implementations welcome. Start with CONTRIBUTING.md. Tests: pip install -e .[dev] && pytest.
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.