Metadata-Version: 2.4
Name: instagram-dl
Version: 0.1.7
Summary: Async Instagram downloader CLI — profiles, posts, reels, stories, highlights, hashtags, comments. Pluggable backends (HikerAPI / aiograpi).
Project-URL: Homepage, https://subzeroid.github.io/insta-dl/
Project-URL: Documentation, https://subzeroid.github.io/insta-dl/
Project-URL: Repository, https://github.com/subzeroid/insta-dl
Project-URL: Issues, https://github.com/subzeroid/insta-dl/issues
Project-URL: Changelog, https://github.com/subzeroid/insta-dl/blob/main/CHANGELOG.md
Author: subzeroid
License: MIT License
        
        Copyright (c) 2026 subzeroid
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: aiograpi,async,cli,downloader,hikerapi,instagram,instagram-downloader,instagram-scraper,osint
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: argcomplete>=3
Requires-Dist: hikerapi
Requires-Dist: tqdm>=4.66
Provides-Extra: aiograpi
Requires-Dist: aiograpi; extra == 'aiograpi'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs>=1.6; extra == 'docs'
Requires-Dist: pymdown-extensions>=10; extra == 'docs'
Provides-Extra: lint
Requires-Dist: mypy>=1.11; extra == 'lint'
Requires-Dist: ruff>=0.6; extra == 'lint'
Description-Content-Type: text/markdown

# insta-dl

[![PyPI](https://img.shields.io/pypi/v/instagram-dl.svg)](https://pypi.org/project/instagram-dl/)
[![Python](https://img.shields.io/pypi/pyversions/instagram-dl.svg)](https://pypi.org/project/instagram-dl/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Tests](https://github.com/subzeroid/insta-dl/actions/workflows/tests.yml/badge.svg)](https://github.com/subzeroid/insta-dl/actions/workflows/tests.yml)
[![codecov](https://codecov.io/gh/subzeroid/insta-dl/branch/main/graph/badge.svg)](https://codecov.io/gh/subzeroid/insta-dl)
[![Docs](https://img.shields.io/badge/docs-subzeroid.github.io-blue)](https://subzeroid.github.io/insta-dl/)

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

![demo](docs/demo.gif)

```bash
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:

```bash
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](https://hikerapi.com/p/18j4ib4j) — **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).

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

📖 **[Full documentation](https://subzeroid.github.io/insta-dl/)** — installation, CLI reference, backends comparison, Python API, troubleshooting.

## How to download an Instagram profile

```bash
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

```bash
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

```bash
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

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

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

## How to grab stories and highlights

```bash
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

```bash
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** |
|---|---|---|
| Auth | API token | Instagram login + 2FA |
| Cost | Paid per request, [**100 free requests**](https://hikerapi.com/p/18j4ib4j) 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`:

```bash
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](https://subzeroid.github.io/insta-dl/backends/). For how insta-dl stacks up against instaloader, yt-dlp, and gallery-dl, see [compared to alternatives](https://subzeroid.github.io/insta-dl/comparison/).

## 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**. Both backends (hiker, aiograpi) are functional end-to-end (278 tests, 96% coverage). aiograpi 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:

- `:feed` and `:saved` targets (account-bound, would need session reuse from aiograpi backend)

See the [changelog](CHANGELOG.md) for what landed when, and [contributing](CONTRIBUTING.md) for how to help.

## Contributing

Bug reports, fixes, and backend implementations welcome. Start with [CONTRIBUTING.md](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](LICENSE).
