Registry / http-networking / instaloader

instaloader

JSON →
library4.15.1pypypi✓ verified 84d ago

Instaloader is an open-source Python tool designed to download pictures and videos, along with their captions and other metadata, from Instagram. It's a popular choice for data hoarders, researchers, and backup enthusiasts for automated archiving of public or private Instagram accounts and hashtags. The library is actively maintained, with its current version being 4.15.1, and releases occurring periodically to adapt to Instagram's changes.

pip install instaloader
INSTALL
IMPORT
SIG · INSTALOADER
I
instaloader
http-networkingpythonv4.15.1
Install
2.2s avg
Import
604ms
Disk
20MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v4.15.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 0.639s · 21.7MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 2.2s · import 0.569s · 22MB
20MB installed
● package 20MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Instaloader
from instaloader import Instaloader
import instaloader # then instaloader.Instaloader()
While 'import instaloader' works, directly importing 'Instaloader' is the idiomatic way to access the main class.

This quickstart demonstrates how to instantiate Instaloader, optionally log in using environment variables (recommended for security and to handle private profiles/rate limits), and then download posts from a specified public profile. The login attempts to reuse a saved session file, falling back to a fresh login if no file is found.

import instaloader import os # Instantiate Instaloader L = instaloader.Instaloader() # Get username and password from environment variables for security USERNAME = os.environ.get('INSTA_USERNAME', 'your_instagram_username') PASSWORD = os.environ.get('INSTA_PASSWORD', 'your_instagram_password') # Check if login credentials are provided and attempt login if USERNAME and PASSWORD and USERNAME != 'your_instagram_username': try: L.load_session_from_file(USERNAME) # Try to load existing session except FileNotFoundError: # If no session file, log in try: L.login(USERNAME, PASSWORD) L.save_session_to_file() # Save session for future use except Exception as e: print(f"Login failed: {e}. You might need to log in via browser and complete a checkpoint, or provide correct credentials.") exit() else: print("Warning: INSTA_USERNAME and INSTA_PASSWORD environment variables not set. Cannot download private profiles or bypass aggressive rate limits.") # Example: Download a public profile (replace 'instagram' with target username) target_profile_name = 'instagram' print(f"Downloading posts for profile: {target_profile_name}") try: profile = instaloader.Profile.from_username(L.context, target_profile_name) for post in profile.get_posts(): L.download_post(post, "#" + target_profile_name) print(f"Successfully downloaded posts for {target_profile_name}") except Exception as e: print(f"Error downloading profile {target_profile_name}: {e}")
instaloader --version
Debug
Known issues
breakingIn version 4.7, the default values for `download_geotags` and `download_comments` in the `Instaloader()` constructor changed from `True` to `False`.
fix
Explicitly set `download_geotags=True` or `download_comments=True` when initializing Instaloader if you rely on this functionality.
affects: >=4.7
gotchaInstagram aggressively rate-limits requests, leading to '429 Too Many Requests' errors. Running multiple Instaloader instances, rapidly restarting, or using VPN/cloud IPs without login often triggers this.
fix
Always use `--login` (or `L.login()` in Python) and ensure a session file is saved and reused. Wait for temporary bans to expire. Avoid concurrent operations. For updates, prefer `--fast-update` or `--latest-stamps`.
affects: All versions
gotchaLogin attempts can fail with 'Checkpoint required' errors, particularly when Instagram detects unusual activity or a new login location.
fix
If a checkpoint error occurs, log in to the Instagram account manually via a web browser, complete any verification steps, and then retry Instaloader. Ensure session files are maintained (e.g., `L.save_session_to_file()`).
affects: All versions
gotchaTo download content from private Instagram profiles, your account must follow the target profile, and you must log in to Instaloader with valid credentials.
fix
Ensure the logged-in Instagram account follows the private target profile. Use `L.login(username, password)` in your script or the `--login` flag with the CLI.
affects: All versions
Errors
Common errors & fixes
instaloader.exceptions.ConnectionException: Login: Checkpoint required.
Instagram's security systems detected suspicious login activity, requiring manual verification through a web browser.
fix
Open a web browser, log in to your Instagram account, complete the required security checkpoint (e.g., entering a code, confirming identity), then close the browser and retry running Instaloader. Ensure you have a saved session file, or use `L.save_session_to_file()` after a successful interactive login.
JSON decode fail, 403 - Forbidden.
Often related to Instagram API changes or outdated session cookies, preventing Instaloader from parsing responses.
fix
Delete your existing session file (usually `~/.config/instaloader/session-YOUR_USERNAME`) and perform a fresh login. Ensure you are using the latest version of Instaloader (`pip install --upgrade instaloader`).
429 Too Many Requests
Instagram's server-side rate limits have been hit. This can happen due to too many requests in a short period, using unauthenticated access, or using IPs frequently associated with scraping (VPNs, cloud servers).
fix
Ensure you are logged in using `L.login()` or `--login`. If logged in, Instaloader will attempt to wait. For CLI, avoid frequent restarts and consider `--fast-update` for incremental downloads. If issues persist, wait a longer period before retrying.
"Too many queries in the last time." (printed to console, but not an exception)
Instaloader's internal rate controller is detecting that Instagram's API rate limits are being approached and is proactively pausing to avoid a hard ban.
fix
This is a notice, not an error, and Instaloader should resume automatically after a delay. This message is more common for unauthenticated requests or when downloading large amounts of data. Ensure you are logged in for potentially higher rate limits.
Upgrade
Version history
4.15.1latest on PyPI · released Mar 21, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
6 hits · last 30 days
node
6
Resources
instaloader — pip install instaloader · libregistry