instagrapi
⚠️ Telegram support group moved to aiograpi_support — the previous
@instagrapigroup 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.
Private API automation is fragile in production because account trust, proxies, device state, challenges, and rate limits can change independently of the library. For account-owned business workflows, prefer official Instagram APIs where they cover your use case. For production private API infrastructure, a hosted provider such as HikerAPI may be a better fit than maintaining accounts, proxies, and challenge handling yourself.
The instagrapi project is best suited for testing, research, and controlled internal automation.
✨ 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
Optional public web TLS impersonation support is available as an extra:
pip install "instagrapi[curl]"
Use it only for public web endpoints that are sensitive to browser TLS fingerprints:
cl = Client(public_transport="curl", public_transport_impersonate="chrome136")
See the public transport guide for live comparison results and caveats.
TLS certificate verification is enabled by default. For a trusted debugging MITM proxy, prefer Client(tls_verify="/path/to/proxy-ca.pem"); use Client(tls_verify=False) only for temporary local debugging because it allows session interception.
If your project uses uv, you can add the package with:
uv add instagrapi
Or install it into the active virtual environment:
uv pip install instagrapi
Video uploads can use a built-in MP4 metadata parser when you provide thumbnail=.... Automatic thumbnail generation, StoryBuilder, and video/audio composition still need the optional video dependencies, MoviePy 2.2.1, and executable ffmpeg:
pip install "instagrapi[video]"
pip install --no-deps "moviepy==2.2.1"
MoviePy 2.2.1 currently declares Pillow<12, but instagrapi keeps Pillow>=12.2.0 for security fixes; the --no-deps install keeps the safe Pillow version. If your project imports MoviePy directly, migrate any MoviePy 1.x code from moviepy.editor, set_*, resize, and subclip APIs to the MoviePy 2.x API before upgrading.
Android users should see Pydroid and ffmpeg and Termux.
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)
Runnable Examples
Practical scripts live in examples/README.md. They cover session login, public lookups, media downloads, feed uploads, Reels and Trial Reels, story uploads, Direct messages, proxies, challenge handling, and optional curl-backed public transport.
Session Persistence
from instagrapi import Client
cl = Client()
cl.login(USERNAME, PASSWORD)
cl.dump_settings("session.json")
# reload later; the saved session is validated before reuse
cl = Client()
cl.load_settings("session.json")
cl.login(USERNAME, PASSWORD)
cl.dump_settings("session.json")
login() reuses a valid saved session. If Instagram rejects that session with
login_required, instagrapi clears the stale authorization and logs in again
with the supplied credentials. Dump the settings after login so a refreshed
session is persisted.
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)
cl.dump_settings("session.json")
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.
If a browser/web sessionid returns login_required or logs the browser out, Instagram rejected that session for the private mobile API. Use a stable password login once, save settings with dump_settings(), and reuse those settings instead of repeatedly importing browser cookies.
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)
Send and read Direct messages
from instagrapi import Client
cl = Client()
cl.login(USERNAME, PASSWORD)
target_id = cl.user_id_from_username("target_user")
sent = cl.direct_send("Hello from instagrapi", user_ids=[target_id])
print("sent", sent.id)
threads = cl.direct_threads(amount=5)
for thread in threads:
last_message = thread.messages[0] if thread.messages else None
print(thread.id, thread.thread_title, last_message.text if last_message else "")
Work with Direct messages over Realtime MQTT
Realtime MQTT support is experimental. It opens Instagram's private MQTToT
connection after login, emits live callbacks, and uses the same Client.proxy
settings as HTTP requests. The realtime client can receive Direct message sync
events and publish lightweight Direct actions such as text, reactions, typing,
and seen state. Use the regular direct_* methods for media sends and full
thread management.
import json
from instagrapi import Client
cl = Client()
cl.login(USERNAME, PASSWORD)
def handle_direct_message(payload):
print(json.dumps(payload, indent=2, ensure_ascii=False))
cl.realtime_on("message", handle_direct_message)
rt = cl.realtime_connect()
rt.direct_subscribe()
try:
rt.ping()
rt.direct_send_text(THREAD_ID, "Hello from MQTT")
while True:
rt.read_once()
finally:
cl.realtime_disconnect()
See the full Realtime MQTT guide for lower-level subscriptions and event details.
Receive Direct push notifications over FBNS
FBNS uses Instagram's separate push MQTT connection and registers an Android push token for the logged-in session. It is useful when you need push payloads such as Direct notification callbacks.
import json
from instagrapi import Client
cl = Client()
cl.login(USERNAME, PASSWORD)
def handle_push(payload):
print(json.dumps(payload, indent=2, ensure_ascii=False))
cl.fbns_on("push", handle_push)
fbns = cl.fbns_connect()
try:
fbns.ping()
while True:
cl.fbns_read_once()
finally:
cl.fbns_disconnect()
Features
- Uses Web API and Mobile API flows where available
- Supports login by password, 2FA, 8-digit backup codes,
sessionid, and Bloks 2FA fallback/helpers for newer verification flows - 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
- Exposes account notification setting helpers with typed notification categories
- Supports story building with mentions, hashtags, link stickers, and media stickers
- Includes helpers for current location search and Direct message workflows
- Supports mobile follower sorting with
date_followed_latestanddate_followed_earliest - App-side discovery surfaces:
chaining,fetch_suggestion_details,discover_recommended_accounts_for_category_v1,user_stream_*,user_web_profile_info_v1 - v2 search SERPs:
media_search,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 - Experimental Realtime MQTT helpers for live events, Direct message sync, lightweight Direct actions, and FBNS push callbacks
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: aiograpi_support — the previous
@instagrapigroup 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 —
bad_password,challenge_required,login_required,please_wait_a_few_minutes,feedback_required,proxy_address_is_blocked BadPassword: correct password rejected by Instagram — proxy/IP/device/session trust troubleshooting- 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)],
)
Related Projects
If you need async Python, use aiograpi.
For other languages, see instagrapi-rest. For hosted production Instagram API infrastructure, see HikerAPI.
Related services:
- 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
For local setup, tests, linting, and pull request expectations, see CONTRIBUTING.md and the development guide.
Maintainer release commands:
git tag -a X.Y.Z -m "Release X.Y.Z"
git push origin X.Y.Z
git push codeberg X.Y.Z
The tag-based publish.yml workflow publishes to PyPI via trusted publishing and creates the GitHub release.
License
instagrapi is distributed under the MIT License.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file instagrapi-2.18.14.tar.gz.
File metadata
- Download URL: instagrapi-2.18.14.tar.gz
- Upload date:
- Size: 223.6 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
911002a07d1bcfe387b1a8bcd8f441c37b65d50cfa24cf5719e99bd6c8d18c90
|
|
| MD5 |
1196be1e2162fd2cf0e3d837a141de2d
|
|
| BLAKE2b-256 |
4c6b8f869ec0d2af43e4395a76cfece4b9ef9fd871d19bf02949efdcdde34ac7
|
Provenance
The following attestation bundles were made for instagrapi-2.18.14.tar.gz:
Publisher:
publish.yml on subzeroid/instagrapi
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
instagrapi-2.18.14.tar.gz -
Subject digest:
911002a07d1bcfe387b1a8bcd8f441c37b65d50cfa24cf5719e99bd6c8d18c90 - Sigstore transparency entry: 2439547018
- Sigstore integration time:
-
Permalink:
subzeroid/instagrapi@27e2ca48444843f845c951286bc762ac1dab7d9d -
Branch / Tag:
refs/tags/2.18.14 - Owner: https://github.com/subzeroid
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@27e2ca48444843f845c951286bc762ac1dab7d9d -
Trigger Event:
push
-
Statement type:
File details
Details for the file instagrapi-2.18.14-py3-none-any.whl.
File metadata
- Download URL: instagrapi-2.18.14-py3-none-any.whl
- Upload date:
- Size: 242.0 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
73bb231627f48197e75cbc4a845392327a3bcf615f2998064b15aa3a22d3b222
|
|
| MD5 |
8876d7dc7baff915c49cfd76a13eabd8
|
|
| BLAKE2b-256 |
f458548cb1e7d449f6a5bfd2de8016ce6d30edbe4a9a470409f117b57f3d3b79
|
Provenance
The following attestation bundles were made for instagrapi-2.18.14-py3-none-any.whl:
Publisher:
publish.yml on subzeroid/instagrapi
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
instagrapi-2.18.14-py3-none-any.whl -
Subject digest:
73bb231627f48197e75cbc4a845392327a3bcf615f2998064b15aa3a22d3b222 - Sigstore transparency entry: 2439547100
- Sigstore integration time:
-
Permalink:
subzeroid/instagrapi@27e2ca48444843f845c951286bc762ac1dab7d9d -
Branch / Tag:
refs/tags/2.18.14 - Owner: https://github.com/subzeroid
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@27e2ca48444843f845c951286bc762ac1dab7d9d -
Trigger Event:
push
-
Statement type:
