{"id":7308,"library":"instaloader","title":"Instaloader","description":"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.","status":"active","version":"4.15.1","language":"en","source_language":"en","source_url":"https://github.com/instaloader/instaloader","tags":["instagram","scraper","download","social media","automation","osint","media"],"install":[{"cmd":"pip install instaloader","lang":"bash","label":"Install with pip"}],"dependencies":[],"imports":[{"note":"While 'import instaloader' works, directly importing 'Instaloader' is the idiomatic way to access the main class.","wrong":"import instaloader # then instaloader.Instaloader()","symbol":"Instaloader","correct":"from instaloader import Instaloader"}],"quickstart":{"code":"import instaloader\nimport os\n\n# Instantiate Instaloader\nL = instaloader.Instaloader()\n\n# Get username and password from environment variables for security\nUSERNAME = os.environ.get('INSTA_USERNAME', 'your_instagram_username')\nPASSWORD = os.environ.get('INSTA_PASSWORD', 'your_instagram_password')\n\n# Check if login credentials are provided and attempt login\nif USERNAME and PASSWORD and USERNAME != 'your_instagram_username':\n    try:\n        L.load_session_from_file(USERNAME) # Try to load existing session\n    except FileNotFoundError: # If no session file, log in\n        try:\n            L.login(USERNAME, PASSWORD)\n            L.save_session_to_file() # Save session for future use\n        except Exception as e:\n            print(f\"Login failed: {e}. You might need to log in via browser and complete a checkpoint, or provide correct credentials.\")\n            exit()\nelse:\n    print(\"Warning: INSTA_USERNAME and INSTA_PASSWORD environment variables not set. Cannot download private profiles or bypass aggressive rate limits.\")\n\n# Example: Download a public profile (replace 'instagram' with target username)\ntarget_profile_name = 'instagram'\nprint(f\"Downloading posts for profile: {target_profile_name}\")\ntry:\n    profile = instaloader.Profile.from_username(L.context, target_profile_name)\n    for post in profile.get_posts():\n        L.download_post(post, \"#\" + target_profile_name)\n    print(f\"Successfully downloaded posts for {target_profile_name}\")\nexcept Exception as e:\n    print(f\"Error downloading profile {target_profile_name}: {e}\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Explicitly set `download_geotags=True` or `download_comments=True` when initializing Instaloader if you rely on this functionality.","message":"In version 4.7, the default values for `download_geotags` and `download_comments` in the `Instaloader()` constructor changed from `True` to `False`.","severity":"breaking","affected_versions":">=4.7"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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()`).","message":"Login attempts can fail with 'Checkpoint required' errors, particularly when Instagram detects unusual activity or a new login location.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"To download content from private Instagram profiles, your account must follow the target profile, and you must log in to Instaloader with valid credentials.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"Instagram's security systems detected suspicious login activity, requiring manual verification through a web browser.","error":"instaloader.exceptions.ConnectionException: Login: Checkpoint required."},{"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`).","cause":"Often related to Instagram API changes or outdated session cookies, preventing Instaloader from parsing responses.","error":"JSON decode fail, 403 - Forbidden."},{"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.","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).","error":"429 Too Many Requests"},{"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.","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.","error":"\"Too many queries in the last time.\" (printed to console, but not an exception)"}]}