Install & Compatibility
Where this runs
tested against v2.8.13 · 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
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 1.394s · 61.1MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 6.1s · import 1.298s · 62MB
85MB installed
● package 85MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Client
✓ from instagrapi import Client
exceptions
✓ from instagrapi import exceptions
✗ from instagrapi.client 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`.
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.")
Errors
Common errors & fixes
instagrapi.exceptions.ChallengeRequired
Instagram's security system has detected suspicious login activity or automated behavior, requiring additional verification (e.g., SMS, email code, or a password change) to prove account ownership.
fixImplement a `challenge_code_handler` or `change_password_handler` in your `Client` setup to automatically or manually resolve the challenge. Sometimes, simply logging in manually through the official Instagram app or website and clearing the challenge can resolve it temporarily.
ModuleNotFoundError: No module named 'instagrapi'
The `instagrapi` library is not installed in the Python environment you are currently using, or your IDE/script is configured to use a different Python interpreter.
fixInstall the library using `pip install instagrapi`. If using a virtual environment, ensure it is activated before installation and that your IDE/script is configured to use that specific environment.
instagrapi.exceptions.ClientUnauthorizedError: 401 Client Error: Unauthorized for url:
Instagram has rejected your authentication attempt. This often means your session is invalid, the username or password is incorrect, or the account has been temporarily blocked or flagged.
fixDouble-check your username and password. Try logging in again with `client.login(username, password)`. For persistent use, implement session saving and loading using `client.dump_settings()` and `client.load_settings()` to avoid repeated logins and reduce suspicion.
instagrapi.exceptions.UnknownError: We couldn't find an account with the username
Instagram's API returned an 'account not found' message, which can genuinely mean the username is incorrect, the account is disabled, or it can be a generic error indicating an IP ban or a problem with the proxy being used.
fixVerify the username for typos. If the username is correct, try using a different, high-quality proxy or no proxy if you're developing locally. Ensure your account is not banned or flagged on Instagram.
requests.exceptions.RetryError: HTTPSConnectionPool(host='i.instagram.com', port=443): Max retries exceeded with url:
This error typically occurs when `instagrapi` (which uses the `requests` library internally) fails to establish or maintain a connection to Instagram's servers, often due to an unresponsive, slow, or blocked proxy, or network issues.
fixEnsure your internet connection is stable. If using a proxy, verify its functionality, ensure it's high-quality, and try a different proxy. Instagram often blocks known datacenter IPs, so residential proxies are generally recommended.
Upgrade
Version history
2.10.2latest on PyPI · released Jun 13, 2026
Audit
Dependencies
No dependency data recorded yet.