What it is
Instaloader is a Python library to download Instagram photos, videos, stories, IGTV, and profiles. It allows you to scrape Instagram content programmatically for personal or research purposes.
Instaloader can download posts, stories, profiles, or hashtags using Python scripts or command-line interface. It supports login for private profiles, filtering by date, and storing metadata in JSON files.
Installation
pip install instaloaderGetting started
The smallest useful thing you can do with it, and what each part means.
import instaloader
L = instaloader.Instaloader()
L.download_profile('instagram_username', profile_pic=True)import instaloader
L = instaloader.Instaloader()
L.download_stories(userids=['instagram_user_id'])Advanced usage
Where the library earns its place over a simpler alternative.
import instaloader
L = instaloader.Instaloader()
L.login('your_username', 'your_password')
L.download_profile('private_user', profile_pic=True)import instaloader
L = instaloader.Instaloader()
for post in instaloader.Hashtag.from_name(L.context, 'python').get_posts():
L.download_post(post, target='#python')import instaloader
L = instaloader.Instaloader(download_comments=False, save_metadata=True)
L.download_profile('instagram_username')import instaloader
import datetime
L = instaloader.Instaloader()
PROFILE = instaloader.Profile.from_username(L.context, 'instagram_username')
for post in PROFILE.get_posts():
if post.date > datetime.datetime(2025,1,1):
L.download_post(post, target=PROFILE.username)Errors and fixes
The failures you are most likely to hit, and what actually resolves them.
- instaloader.exceptions.LoginRequiredException
- Login using L.login('username', 'password') to access private content.
- instaloader.exceptions.ProfileNotExistsException
- Verify that the Instagram username exists and is spelled correctly.
- instaloader.exceptions.ConnectionException
- Check network connectivity and Instagram server availability.
Best practices
- Respect Instagram’s terms of service and avoid excessive scraping.
- Use login for private content responsibly and only for accounts you have access to.
- Handle exceptions for network issues or blocked content.
- Save metadata and use structured directories for organization.
- Rate-limit requests to avoid temporary bans or throttling.
Background
Why it exists, and what it was reacting to.
Instaloader was created by Thilo Planz to provide a simple and efficient tool for downloading content from Instagram without using the official API. It handles login, private profiles, hashtags, and profiles with ease, and can save metadata like captions, likes, and comments.