Instaloader

Common errors

• instaloader.exceptions.ConnectionException: Login: Checkpoint required.

  cause 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.

  cause 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

  cause 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)

  cause 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.

Warnings

• breaking In 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.
• gotcha Instagram 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`.
• gotcha Login 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()`).
• gotcha To 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.

Install

• pip install instaloader Install with pip

Imports

• Instaloader
  wrong:

  import instaloader # then instaloader.Instaloader()

  correct:

  from instaloader import Instaloader

  While 'import instaloader' works, directly importing 'Instaloader' is the idiomatic way to access the main class.

Quickstart

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}")