Instaloader: a Python CLI for archiving Instagram profiles, stories and metadata

The gap Instaloader fills for Instagram archives

Instagram does not offer a supported way to pull a full profile, its stories, and its per-post metadata into a local directory tree. The official data export is account-scoped and slow. Instaloader targets the opposite need: a command-line program that walks a named profile, hashtag or feed and writes media plus captions, comments and geotags to disk. The README's own summary is that it downloads public and private profiles, hashtags, user stories, feeds and saved media, and that it captures comments, geotags and captions of each post. That combination is what separates it from a plain image downloader. The audience is engineers and researchers who want files they control: OSINT work, dataset assembly, personal backups, or a cron job that keeps a mirror current. The repository topics list osint and osint-python alongside downloader and instagram-scraper, which matches how the tool is actually used. It is not a mobile app and not a hosted service; the README ships a console entry point named instaloader and nothing else.

How Instaloader structures a download

Instaloader is a Python package with a console script, and the target of a run is one of four kinds of identifier: a profile name, a #hashtag, or one of the special targets :stories, :feed and :saved. The README's usage line shows the shape: instaloader with flags, then the target. The flags decide what gets fetched. --comments pulls post comments, --geotags pulls location data, --stories and --highlights pull ephemeral and pinned story content, --tagged pulls posts the profile is tagged in, and --reels and --igtv pull those two video surfaces. Output lands in a directory named after the profile. Two behaviours matter for anyone running this on a schedule. First, the tool detects profile name changes and renames the target directory accordingly, so a rename does not silently fork your archive into two folders. Second, interrupted iterations resume: the README states it automatically resumes previously-interrupted download iterations. That resume logic is what makes a long backfill survivable on a flaky connection. The Python API is the other half of the mechanism, since instaloader is importable as a package and the setup.py declares package_data including py.typed, so type information ships with the distribution.

Installing Instaloader and running a first download

The README gives the install as a single pip command. Python 3.9 or newer is required; setup.py exits with an explicit message if the interpreter is older. The only hard dependency is requests>=2.25.

pip3 install instaloader

After that, the console script is on your PATH. To download everything the README describes as "all pictures and videos of a profile", plus the profile picture, pass one or more profile names. The README notes you may specify a list of profiles instead of just one.

instaloader profile

To keep that copy current, the README offers two update strategies. --fast-update stops when it reaches the first already-downloaded picture, which is cheap but assumes the archive is contiguous. --latest-stamps stores the time each profile was last downloaded and only fetches newer media, which the README says lets you move or delete downloaded media and still keep the archive updated. Note the double dash before the profile name in the README's example.

instaloader --fast-update profile
instaloader --latest-stamps -- profile

Private profiles need a login. The README shows --login=your_username, and states that session cookies are stored in a file in your temporary directory and reused the next time --login is given, so later runs can be non-interactive once a valid cookie file exists.

instaloader --login=your_username profile

Rate limits, breakage and the cases where Instaloader is the wrong tool

The README does not document rate limits, retry policy, or what happens when Instagram changes an endpoint. That silence is the main operational risk. Because Instaloader talks to an unofficial private API, a change on Instagram's side can break a run with no deprecation window and no changelog entry that maps to your failure. The release cadence is uneven: v4.15.1 landed on 2026-03-21, v4.15.2 on 2026-07-05, and v4.15.3 on 2026-07-26, so gaps of a few months between fixes are normal. If your pipeline needs a support contract, a status page, or an SLA, this is the wrong tool. It is also the wrong tool for bulk historical research where you cannot tolerate partial archives: the README does not document rollback, so a run that fails midway leaves you reconciling directories by hand. Session handling is a second boundary. The cookie file lives in your temporary directory, which means a reboot or a tmp cleaner can invalidate a long-running non-interactive setup, and the README does not describe a way to pin that path. Finally, the README's disclaimer is explicit that Instaloader is in no way affiliated with, authorized, maintained or endorsed by Instagram, and that you use it at your own risk. Treat account safety as your problem, not the tool's.

Instaloader against gallery-dl and yt-dlp

The natural comparison is gallery-dl, which also downloads media from many sites including Instagram, and yt-dlp, which handles video-first sources. The difference is scope and depth. gallery-dl is a multi-site extractor: one binary, many sites, a config file, and post-processors for renaming and metadata. Instaloader is single-site and goes deeper on that one site: it models Instagram-specific surfaces as first-class targets (:stories, :feed, :saved, --tagged, --highlights, --reels, --igtv) and it treats comments and geotags as downloadable fields rather than optional extras. It also carries Instagram-specific state, namely profile-rename detection and the resume behaviour described in the README. yt-dlp is aimed at video streams and does not model profile archives or comment metadata the same way. The practical split: pick gallery-dl if you need one tool for a dozen sites and are willing to accept shallower Instagram metadata; pick Instaloader if Instagram is the whole job and you need the per-post fields. There is a cost to the narrower focus, and it is the one named above: a single upstream API change takes the entire tool offline rather than one extractor among many.

Licence, upgrades and the real cost of running Instaloader

Instaloader is MIT licensed; the README points to the LICENSE file and the repository root contains it. MIT is permissive, so you can vendor the package, modify it, or ship it inside a commercial pipeline, provided you keep the copyright notice and licence text. That is the extent of what the README supports; questions about how MIT interacts with your own distribution obligations belong with your counsel, not with this article. Upgrades are cheap in the mechanical sense: pip3 install --upgrade instaloader, or a version pin in your requirements file. The real cost is verification. Because there is no documented compatibility contract with Instagram's API, every upgrade is a candidate for a behaviour change you discover only when a nightly job returns nothing. Pin the version, run the pinned version against a small test profile after each bump, and keep the previous version available to roll back to. The optional browser_cookie3 extra (>=0.19.1) exists for cookie import, which adds a dependency you should only take if you actually need it. Maintenance is ongoing: the most recent push to the default branch was on 2026-09-06, after the v4.15.3 release on 2026-07-26.

Editorial conclusion

Adopt Instaloader when you need a scriptable, local archive of Instagram media and metadata and you are comfortable managing session cookies and rate limits yourself. Avoid it if you need a hosted dashboard, guaranteed uptime, or a supported commercial SLA; the project is independent and unofficial, and the README states it is not affiliated with Instagram. Before committing, verify that your Python is 3.9 or newer, confirm that --login works against your account, and test --fast-update or --latest-stamps on a throwaway profile so you understand which of the two resume strategies fits your disk layout.

Frequently asked questions

Official sources

1. instaloader/instaloader on GitHub
2. License: MIT
3. Project website
4. README
5. Releases