instagrapi 2.4.1

Fast and effective Instagram Private API wrapper

instagrapi

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

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 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

Documentation And Support

• Documentation index
• Getting Started
• Usage Guide
• GitHub Discussions
• Support chat in Telegram

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

ASCII Logo

░██                         ░██                                                         ░██
                            ░██
░██░████████   ░███████  ░████████  ░██████    ░████████ ░██░████  ░██████   ░████████  ░██
░██░██    ░██ ░██           ░██          ░██  ░██    ░██ ░███           ░██  ░██    ░██ ░██
░██░██    ░██  ░███████     ░██     ░███████  ░██    ░██ ░██       ░███████  ░██    ░██ ░██
░██░██    ░██        ░██    ░██    ░██   ░██  ░██   ░███ ░██      ░██   ░██  ░███   ░██ ░██
░██░██    ░██  ░███████      ░████  ░█████░██  ░█████░██ ░██       ░█████░██ ░██░█████  ░██
                                                     ░██                     ░██
                                               ░███████                      ░██

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)]
)

Documentation

• Index
• Getting Started
• Usage Guide
• Interactions
  • Media - Publication (also called post): Photo, Video, Album, IGTV and Reels
  • Resource - Part of Media (for albums)
  • MediaOembed - Short version of Media
  • Account - 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 data
  • UserShort - 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 Media
  • Highlight - Highlights
  • Notes - Notes
  • Story - Story
  • StoryLink - Story link sticker
  • StoryLocation - 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-ordinates
  • DirectThread - Thread (topic) with messages in Direct Message
  • DirectMessage - Message in Direct Message
  • Insight - Insights for a post
  • Track - Music track (for Reels/Clips)
• Best Practices
• Development Guide
• Handle Exceptions
• Challenge Resolver
• Exceptions

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 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

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/*