instagrapi

Warnings

• breaking Instagram's API is private and constantly changing. `instagrapi` relies on reverse-engineering, which means it can break at any time without warning from Instagram.
  Fix: Always keep `instagrapi` updated to the latest version. Monitor the GitHub repository for new releases and breaking changes. Be prepared for your scripts to stop working unexpectedly and require an update.
• gotcha Persistent login requires proper handling of session settings. Failing to load or dump settings means you'll have to re-authenticate (and potentially face login challenges) on every script run.
  Fix: Use `cl.dump_settings(path)` after successful login and `cl.load_settings(path)` at the start of your script to reuse sessions. Store the settings file securely.
• gotcha Instagram aggressive rate-limiting and IP bans are common. Operating without proxies, especially for high-volume tasks, will quickly lead to your IP being blocked.
  Fix: Utilize a high-quality, rotating proxy pool with `cl = Client(proxy='http://your.proxy.com:port')`. Change proxies frequently and introduce delays between requests to mimic human behavior.
• gotcha Login challenges (e.g., 2FA, email/SMS verification, CAPTCHA) are frequent. `instagrapi` provides mechanisms to handle these, but it often requires custom code.
  Fix: Implement error handling for `instagrapi.exceptions.ChallengeRequired`, `LoginRequired`, and similar exceptions. Refer to the official documentation for specific challenge handling strategies like `cl.challenge_resolve()`.

Install

• pip install instagrapi Install latest version

Imports

• Client

  from instagrapi import Client

• exceptions

  from instagrapi import exceptions

  Exceptions are typically found under the top-level `instagrapi.exceptions` module, not directly under `instagrapi` or `instagrapi.client`.
• LoginRequired

  from instagrapi.exceptions import LoginRequired

• Media

  from instagrapi.types import Media

  Common data structures like `User`, `Media`, `Story` are found in `instagrapi.types`.

Quickstart

This quickstart demonstrates how to initialize `instagrapi.Client`, handle session loading and saving for persistent login, and perform a basic action like fetching user information. It uses environment variables for secure credential management.

import os
from instagrapi import Client

# It's highly recommended to use environment variables for sensitive data
USERNAME = os.environ.get('INSTA_USERNAME', '')
PASSWORD = os.environ.get('INSTA_PASSWORD', '')
SETTINGS_PATH = os.environ.get('INSTA_SETTINGS_PATH', 'instagrapi_settings.json')

if not (USERNAME and PASSWORD):
    print("Warning: INSTA_USERNAME and INSTA_PASSWORD environment variables not set.")
    print("This quickstart will not be able to log in without credentials.")
    # For demonstration, we'll proceed but it will fail at login

cl = Client()

# Attempt to load existing session settings to avoid re-logging in
if os.path.exists(SETTINGS_PATH):
    cl.load_settings(SETTINGS_PATH)
    print("Existing session settings loaded successfully.")
else:
    print("No existing session settings found, attempting to log in...")

# Ensure client is logged in
if not cl.is_logged_in:
    try:
        print(f"Attempting to log in as {USERNAME}...")
        cl.login(USERNAME, PASSWORD)
        cl.dump_settings(SETTINGS_PATH) # Save settings for future use
        print("Logged in successfully and session settings dumped.")
    except Exception as e:
        print(f"Login failed: {e}")
        print("Common reasons: incorrect credentials, 2FA required (handle `ChallengeRequired` exception), IP ban, or Instagram API changes.")
        exit(1)

# Example: Get user info for a public account (e.g., 'instagram')
try:
    user_info = cl.user_info_by_username("instagram")
    print(f"\nFetched info for 'instagram':")
    print(f"  User ID: {user_info.pk}")
    print(f"  Followers: {user_info.follower_count}")
except Exception as e:
    print(f"Could not fetch user info for 'instagram': {e}")
    print("This might happen if you are rate-limited or the API call has changed.")