instagrapi 2.5.13

Fast and effective Instagram Private API wrapper

instagrapi

⚠️ Telegram support group moved to https://t.me/aiograpi_support — the previous @instagrapi group has been restricted by Meta and is no longer maintained.

Fast and effective unofficial Instagram API wrapper for Python.

instagrapi combines public web and private mobile API flows, supports session persistence and challenge handling, and covers the main automation primitives for users, media, stories, direct messages, notes, locations, comments, insights, and uploads.

If you want to work with Instagrapi for business interests, prefer HikerAPI SaaS. You will not need to spend weeks or even months setting it up. The service handles millions of daily requests, provides round-the-clock support, and offers partners a special rate. In many cases, clients first try to save money with self-hosted private API automation, then return to HikerAPI SaaS after spending more time and money on accounts, proxies, and challenge handling. It is difficult to find good accounts, good proxies, resolve challenges reliably, and keep Instagram from banning accounts.

The instagrapi project is better suited for testing and research than for running a production business.

✨ aiograpi - Asynchronous Python library for Instagram Private API ✨

Support Python 3.10+

Python 3.9 support was dropped in 2.5.0. Upstream security patches for Pillow 12.x and pytest 9.x are not backported to Python 3.9, leaving conditional pins permanently exposed to known CVEs. Users who need Python 3.9 should pin to instagrapi==2.4.5.

Installation

pip install instagrapi

Quick Start

from instagrapi import Client

cl = Client()
cl.login(ACCOUNT_USERNAME, ACCOUNT_PASSWORD)

user_id = cl.user_id_from_username(ACCOUNT_USERNAME)
medias = cl.user_medias(user_id, 20)

Session Persistence

from instagrapi import Client

cl = Client()
cl.login(USERNAME, PASSWORD)
cl.dump_settings("session.json")

# reload later without entering credentials again
cl = Client()
cl.load_settings("session.json")
cl.login(USERNAME, PASSWORD)

If you want more explicit control over the loaded session object:

from instagrapi import Client

cl = Client()
cl.set_settings(cl.load_settings("session.json"))
cl.login(USERNAME, PASSWORD)

Login using a sessionid

from instagrapi import Client

cl = Client()
cl.login_by_sessionid("<your_sessionid>")

login_by_sessionid() is best treated as a lightweight compatibility path. For long-lived automation, prefer the normal login() -> dump_settings() -> load_settings()/set_settings() session flow.

Typical Tasks

List and download another user's posts

from instagrapi import Client

cl = Client()
cl.login(USERNAME, PASSWORD)

target_id = cl.user_id_from_username("target_user")
posts = cl.user_medias(target_id, amount=10)
for media in posts:
    # download photos to the current folder
    cl.photo_download(media.pk)

See examples/session_login.py for a standalone script demonstrating these login methods.

Search locations by name or exact pk

from instagrapi import Client

cl = Client()
cl.login(USERNAME, PASSWORD)

places = cl.location_search_name("Times Square")
place = places[0]
same_place = cl.location_search_pk(place.pk)

print(same_place.name, same_place.pk)

Work with Notes

from instagrapi import Client

cl = Client()
cl.login(USERNAME, PASSWORD)

notes = cl.get_notes()
print(cl.get_note_text_by_user(notes, "instagram"))

note = cl.create_note("Hello from instagrapi", audience=0)
cl.delete_note(note.id)

Features

• Uses Web API and Mobile API flows where available
• Supports login by password, 2FA, and sessionid
• Includes email/SMS-based challenge resolver hooks
• Uploads and downloads photos, videos, albums, IGTV, reels, and stories
• Works with users, media, comments, locations, hashtags, collections, notes, direct messages, and insights
• Supports story building with mentions, hashtags, link stickers, and media stickers
• Includes helpers for current location search and notes flows
• App-side discovery surfaces: chaining, fetch_suggestion_details, discover_recommended_accounts_for_category_v1, user_stream_*, user_web_profile_info_v1
• v2 search SERPs: fbsearch_accounts_v2, fbsearch_reels_v2, fbsearch_topsearch_v2, fbsearch_typehead
• Alternative media-info path (media_info_v2) for ad-tagged / sponsored media that the canonical endpoint refuses

Anonymous/public web paths are best treated as opportunistic rather than guaranteed. Instagram can change or restrict them independently of the library, so production-grade workflows should prefer authenticated sessions.

Documentation And Support

API reference and full usage guide live at subzeroid.github.io/instagrapi:

• Documentation index
• Getting Started
• Usage Guide
• Interactions reference
• Best Practices for sessions, proxies, and anti-abuse handling
• Handle Exceptions for centralizing 429, challenge, and relogin logic
• GitHub Discussions
• Support chat in Telegram: https://t.me/aiograpi_support — the previous @instagrapi group was restricted by Meta and is no longer maintained

For other languages, consider instagrapi-rest. For async Python, see aiograpi.

Tutorials

Hands-on guides for real instagrapi work — login flows, sessions, proxies, scraping, posting, error handling — live at instagrapi.com/guides:

• Instagram Private API in Python — pillar walkthrough: login, sessions, fetching, posting
• 2FA and challenge_required
• Session persistence: file, Redis, and Postgres patterns
• Configuring proxies (HTTP, SOCKS5, residential)
• Instagram scraper in Python: a working setup
• Upload a photo from Python
• Download Instagram stories
• Common errors reference — challenge_required, login_required, please_wait_a_few_minutes, feedback_required, proxy_address_is_blocked
• Framework integrations — Django, FastAPI, Celery, Docker, AWS Lambda

Comparing instagrapi to other tools:

• instagrapi vs Instaloader — download-only vs authenticated automation
• instagrapi vs aiograpi — sync or async
• Instagram API libraries by language — what's actually maintained in 2026

Additional example

from instagrapi import Client
from instagrapi.types import StoryMention, StoryMedia, StoryLink, StoryHashtag

cl = Client()
cl.login(USERNAME, PASSWORD, verification_code="<2FA CODE HERE>")

media_pk = cl.media_pk_from_url('https://www.instagram.com/p/CGgDsi7JQdS/')
media_path = cl.video_download(media_pk)
subzeroid = cl.user_info_by_username('subzeroid')
hashtag = cl.hashtag_info('dhbastards')

cl.video_upload_to_story(
    media_path,
    "Credits @subzeroid",
    mentions=[StoryMention(user=subzeroid, x=0.49892962, y=0.703125, width=0.8333333333333334, height=0.125)],
    links=[StoryLink(webUri='https://github.com/subzeroid/instagrapi')],
    hashtags=[StoryHashtag(hashtag=hashtag, x=0.23, y=0.32, width=0.5, height=0.22)],
    medias=[StoryMedia(media_pk=media_pk, x=0.5, y=0.5, width=0.6, height=0.8)]
)

Ecosystem And Hosted Options

If you need async Python, use aiograpi.

If you need hosted infrastructure instead of maintaining accounts, proxies, and challenge handling yourself, consider:

• HikerAPI for production-grade hosted Instagram API infrastructure
• Cloqly for premium rotating proxies and stable automation traffic
• DataLikers for Instagram MCP, Cache API, and datasets
• LamaTok for TikTok API access, automation, and data workflows
• InstaSurfBot for downloading Instagram media in Telegram
• OSINTagramBot for Instagram OSINT in Telegram

HikerAPI Affiliate Program

Refer users to HikerAPI and earn a percentage of their API spending:

Plan	Commission
Start trial plan ($0.02/req)	50%
Standard ($0.001/req)	25%
Business ($0.00069/req)	15%
Ultra ($0.0006/req)	10%

Extras: 2-level referral system, no caps, lifetime attribution

Payouts: USDT / USDC (TRC-20 or ERC-20), minimum 20 USDT, request anytime from the dashboard

Contributing

To release, you need to call the following commands:

python -m build
twine upload dist/*