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.
Support Python >= 3.9
pip install instagrapi
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)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)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.
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.
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)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)- Uses Web API or Mobile API depending on the situation
- 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
For other languages, consider instagrapi-rest. For async Python, see aiograpi.
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)]
)- Index
- Getting Started
- Usage Guide
- Interactions
Media- Publication (also called post): Photo, Video, Album, IGTV and ReelsResource- Part of Media (for albums)MediaOembed- Short version of MediaAccount- Full private info for your account (e.g. email, phone_number)TOTP- 2FA TOTP helpers (generate seed, enable/disable TOTP, generate code as Google Authenticator)User- Full public user dataUserShort- Short public user data (used in Usertag, Comment, Media, Direct Message)Usertag- Tag user in Media (coordinates + UserShort)Location- GEO location (GEO coordinates, name, address)Hashtag- Hashtag object (id, name, picture)Collection- Collection of medias (name, picture and list of medias)Comment- Comments to MediaHighlight- HighlightsNotes- NotesStory- StoryStoryLink- Story link stickerStoryLocation- Tag Location in Story (as sticker)StoryMention- Mention users in Story (user, coordinates and dimensions)StoryHashtag- Hashtag for story (as sticker)StorySticker- Tag sticker to story (for example from giphy)StoryBuild- StoryBuilder return path to photo/video and mention co-ordinatesDirectThread- Thread (topic) with messages in Direct MessageDirectMessage- Message in Direct MessageInsight- Insights for a postTrack- Music track (for Reels/Clips)
- Best Practices
- Development Guide
- Handle Exceptions
- Challenge Resolver
- Exceptions
If you need async Python, use aiograpi.
If you need hosted infrastructure instead of maintaining accounts, proxies, and challenge handling yourself, consider:
- HikerAPI for hosted Instagram API
- Cloqly for rotating proxies
- DataLikers for Instagram datasets, MCP, and CacheAPI
- LamaTok for TikTok API
- InstaSurfBot for downloading Instagram media in Telegram
- OSINTagramBot for Instagram OSINT in Telegram
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
To release, you need to call the following commands:
python -m build
twine upload dist/*