{"id":13467551,"url":"https://github.com/subzeroid/instagrapi","last_synced_at":"2026-06-15T22:00:49.411Z","repository":{"id":37081544,"uuid":"283868135","full_name":"subzeroid/instagrapi","owner":"subzeroid","description":"🔥 The fastest and powerful Python library for Instagram Private API 2026 with HikerAPI SaaS","archived":false,"fork":false,"pushed_at":"2026-06-13T01:50:03.000Z","size":9521,"stargazers_count":6318,"open_issues_count":55,"forks_count":923,"subscribers_count":95,"default_branch":"master","last_synced_at":"2026-06-13T03:26:41.544Z","etag":null,"topics":["api-wrapper","instabot","instagram","instagram-account","instagram-api","instagram-api-python","instagram-automation","instagram-bot","instagram-client","instagram-crawler","instagram-downloader","instagram-feed","instagram-photos","instagram-private-api","instagram-scraper","instagram-sdk","instagram-stories","instagrapi","instaloader","instapy"],"latest_commit_sha":null,"homepage":"https://subzeroid.github.io/instagrapi/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/subzeroid.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"adw0rd","patreon":"adw0rd","custom":["https://boosty.to/adw0rd","adw0rd.com/funding/","buymeacoffee.com/adw0rd"]}},"created_at":"2020-07-30T20:14:10.000Z","updated_at":"2026-06-13T01:49:08.000Z","dependencies_parsed_at":"2026-05-28T03:00:42.281Z","dependency_job_id":null,"html_url":"https://github.com/subzeroid/instagrapi","commit_stats":{"total_commits":1127,"total_committers":83,"mean_commits":"13.578313253012048","dds":0.3824312333629104,"last_synced_commit":"073b748fcf379701a49f3f9adc3a9a780f8e4283"},"previous_names":["subzeroid/instagrapi","adw0rd/instagrapi"],"tags_count":340,"template":false,"template_full_name":null,"purl":"pkg:github/subzeroid/instagrapi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/subzeroid%2Finstagrapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/subzeroid%2Finstagrapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/subzeroid%2Finstagrapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/subzeroid%2Finstagrapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/subzeroid","download_url":"https://codeload.github.com/subzeroid/instagrapi/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/subzeroid%2Finstagrapi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34381762,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-15T02:00:07.085Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-wrapper","instabot","instagram","instagram-account","instagram-api","instagram-api-python","instagram-automation","instagram-bot","instagram-client","instagram-crawler","instagram-downloader","instagram-feed","instagram-photos","instagram-private-api","instagram-scraper","instagram-sdk","instagram-stories","instagrapi","instaloader","instapy"],"created_at":"2024-07-31T15:00:57.807Z","updated_at":"2026-06-15T22:00:49.375Z","avatar_url":"https://github.com/subzeroid.png","language":"Python","funding_links":["https://github.com/sponsors/adw0rd","https://patreon.com/adw0rd","https://boosty.to/adw0rd","adw0rd.com/funding/","buymeacoffee.com/adw0rd"],"categories":["Python","instagram","[🧑‍💻 dev](https://github.com/stars/ketsapiwiq/lists/dev)"],"sub_categories":[],"readme":"# instagrapi\n\n\u003e ⚠️ **Telegram support group moved to [aiograpi_support](https://t.me/aiograpi_support)** — the previous `@instagrapi` group has been restricted by Meta and is no longer maintained.\n\n[![PyPI](https://img.shields.io/pypi/v/instagrapi)](https://pypi.org/project/instagrapi/)\n[![Python](https://img.shields.io/pypi/pyversions/instagrapi)](https://pypi.org/project/instagrapi/)\n[![License](https://img.shields.io/pypi/l/instagrapi)](LICENSE)\n[![Package](https://github.com/subzeroid/instagrapi/actions/workflows/python-package.yml/badge.svg)](https://github.com/subzeroid/instagrapi/actions/workflows/python-package.yml)\n[![Docs](https://img.shields.io/badge/docs-gh--pages-blue)](https://subzeroid.github.io/instagrapi/)\n\nFast and effective unofficial Instagram API wrapper for Python.\n\n`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.\n\nPrivate API automation is fragile in production because account trust, proxies, device state, challenges, and rate limits can change independently of the library.\nFor account-owned business workflows, prefer official Instagram APIs where they cover your use case.\nFor production private API infrastructure, a hosted provider such as [HikerAPI](https://hikerapi.com/) may be a better fit than maintaining accounts, proxies, and challenge handling yourself.\n\nThe instagrapi project is best suited for testing, research, and controlled internal automation.\n\n✨ [aiograpi - Asynchronous Python library for Instagram Private API](https://github.com/subzeroid/aiograpi) ✨\n\nSupport **Python 3.10+**\n\n`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`.\n\n## Installation\n\n```bash\npip install instagrapi\n```\n\nOptional public web TLS impersonation support is available as an extra:\n\n```bash\npip install \"instagrapi[curl]\"\n```\n\nUse it only for public web endpoints that are sensitive to browser TLS fingerprints:\n\n```python\ncl = Client(public_transport=\"curl\", public_transport_impersonate=\"chrome136\")\n```\n\nSee the [public transport guide](docs/usage-guide/public-transport.md) for live comparison results and caveats.\n\nTLS 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.\n\nIf your project uses [uv](https://docs.astral.sh/uv/), you can add the package with:\n\n```bash\nuv add instagrapi\n```\n\nOr install it into the active virtual environment:\n\n```bash\nuv pip install instagrapi\n```\n\nVideo 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`:\n\n```bash\npip install \"instagrapi[video]\"\npip install --no-deps \"moviepy==2.2.1\"\n```\n\nMoviePy `2.2.1` currently declares `Pillow\u003c12`, but instagrapi keeps `Pillow\u003e=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.\n\nAndroid users should see [Pydroid and ffmpeg](docs/usage-guide/pydroid.md) and [Termux](docs/usage-guide/termux.md).\n\n## Quick Start\n\n``` python\nfrom instagrapi import Client\n\ncl = Client()\ncl.login(ACCOUNT_USERNAME, ACCOUNT_PASSWORD)\n\nuser_id = cl.user_id_from_username(ACCOUNT_USERNAME)\nmedias = cl.user_medias(user_id, 20)\n```\n\n## Runnable Examples\n\nPractical scripts live in [examples/README.md](examples/README.md). They cover session login, public lookups, media\ndownloads, feed uploads, Reels and Trial Reels, story uploads, Direct messages, proxies, challenge handling, and optional\ncurl-backed public transport.\n\n## Session Persistence\n\n``` python\nfrom instagrapi import Client\n\ncl = Client()\ncl.login(USERNAME, PASSWORD)\ncl.dump_settings(\"session.json\")\n\n# reload later without entering credentials again\ncl = Client()\ncl.load_settings(\"session.json\")\ncl.login(USERNAME, PASSWORD)\n```\n\nIf you want more explicit control over the loaded session object:\n\n```python\nfrom instagrapi import Client\n\ncl = Client()\ncl.set_settings(cl.load_settings(\"session.json\"))\ncl.login(USERNAME, PASSWORD)\n```\n\n### Login using a sessionid\n\n``` python\nfrom instagrapi import Client\n\ncl = Client()\ncl.login_by_sessionid(\"\u003cyour_sessionid\u003e\")\n```\n\n`login_by_sessionid()` is best treated as a lightweight compatibility path. For long-lived automation, prefer the normal `login() -\u003e dump_settings() -\u003e load_settings()/set_settings()` session flow.\n\nIf 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.\n\n## Typical Tasks\n\n### List and download another user's posts\n\n``` python\nfrom instagrapi import Client\n\ncl = Client()\ncl.login(USERNAME, PASSWORD)\n\ntarget_id = cl.user_id_from_username(\"target_user\")\nposts = cl.user_medias(target_id, amount=10)\nfor media in posts:\n    # download photos to the current folder\n    cl.photo_download(media.pk)\n```\nSee [examples/session_login.py](examples/session_login.py) for a standalone script demonstrating these login methods.\n\n### Search locations by name or exact pk\n\n```python\nfrom instagrapi import Client\n\ncl = Client()\ncl.login(USERNAME, PASSWORD)\n\nplaces = cl.location_search_name(\"Times Square\")\nplace = places[0]\nsame_place = cl.location_search_pk(place.pk)\n\nprint(same_place.name, same_place.pk)\n```\n\n### Send and read Direct messages\n\n```python\nfrom instagrapi import Client\n\ncl = Client()\ncl.login(USERNAME, PASSWORD)\n\ntarget_id = cl.user_id_from_username(\"target_user\")\nsent = cl.direct_send(\"Hello from instagrapi\", user_ids=[target_id])\nprint(\"sent\", sent.id)\n\nthreads = cl.direct_threads(amount=5)\nfor thread in threads:\n    last_message = thread.messages[0] if thread.messages else None\n    print(thread.id, thread.thread_title, last_message.text if last_message else \"\")\n```\n\n### Work with Direct messages over Realtime MQTT\n\nRealtime MQTT support is experimental. It opens Instagram's private MQTToT\nconnection after login, emits live callbacks, and uses the same `Client.proxy`\nsettings as HTTP requests. The realtime client can receive Direct message sync\nevents and publish lightweight Direct actions such as text, reactions, typing,\nand seen state. Use the regular `direct_*` methods for media sends and full\nthread management.\n\n```python\nimport json\n\nfrom instagrapi import Client\n\ncl = Client()\ncl.login(USERNAME, PASSWORD)\n\n\ndef handle_direct_message(payload):\n    print(json.dumps(payload, indent=2, ensure_ascii=False))\n\n\ncl.realtime_on(\"message\", handle_direct_message)\n\nrt = cl.realtime_connect()\nrt.direct_subscribe()\n\ntry:\n    rt.ping()\n    rt.direct_send_text(THREAD_ID, \"Hello from MQTT\")\n    while True:\n        rt.read_once()\nfinally:\n    cl.realtime_disconnect()\n```\n\nSee the full [Realtime MQTT guide](docs/usage-guide/realtime.md) for lower-level\nsubscriptions and event details.\n\n### Receive Direct push notifications over FBNS\n\nFBNS uses Instagram's separate push MQTT connection and registers an Android\npush token for the logged-in session. It is useful when you need push payloads\nsuch as Direct notification callbacks.\n\n```python\nimport json\n\nfrom instagrapi import Client\n\ncl = Client()\ncl.login(USERNAME, PASSWORD)\n\n\ndef handle_push(payload):\n    print(json.dumps(payload, indent=2, ensure_ascii=False))\n\n\ncl.fbns_on(\"push\", handle_push)\nfbns = cl.fbns_connect()\n\ntry:\n    fbns.ping()\n    while True:\n        cl.fbns_read_once()\nfinally:\n    cl.fbns_disconnect()\n```\n\n## Features\n\n* Uses [Web API](https://subzeroid.github.io/instagrapi/usage-guide/fundamentals.html) and [Mobile API](https://subzeroid.github.io/instagrapi/usage-guide/fundamentals.html) flows where available\n* Supports login by password, 2FA, 8-digit backup codes, `sessionid`, and [Bloks 2FA](https://subzeroid.github.io/instagrapi/usage-guide/totp.html#bloks-two-factor-flow) fallback/helpers for newer verification flows\n* Includes email/SMS-based [challenge resolver](https://subzeroid.github.io/instagrapi/usage-guide/challenge_resolver.html) hooks\n* Uploads and downloads photos, videos, albums, IGTV, reels, and stories\n* Works with users, media, comments, locations, hashtags, collections, notes, direct messages, and insights\n* Supports story building with mentions, hashtags, link stickers, and media stickers\n* Includes helpers for current location search and Direct message workflows\n* Supports mobile follower sorting with `date_followed_latest` and `date_followed_earliest`\n* App-side discovery surfaces: `chaining`, `fetch_suggestion_details`, `discover_recommended_accounts_for_category_v1`, `user_stream_*`, `user_web_profile_info_v1`\n* v2 search SERPs: `fbsearch_accounts_v2`, `fbsearch_reels_v2`, `fbsearch_topsearch_v2`, `fbsearch_typehead`\n* Alternative media-info path (`media_info_v2`) for ad-tagged / sponsored media that the canonical endpoint refuses\n* Experimental Realtime MQTT helpers for live events, Direct message sync, lightweight Direct actions, and FBNS push callbacks\n\nAnonymous/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.\n\n## Documentation And Support\n\nAPI reference and full usage guide live at [subzeroid.github.io/instagrapi](https://subzeroid.github.io/instagrapi/):\n\n* [Documentation index](https://subzeroid.github.io/instagrapi/)\n* [Getting Started](https://subzeroid.github.io/instagrapi/getting-started.html)\n* [Usage Guide](https://subzeroid.github.io/instagrapi/usage-guide/fundamentals.html)\n* [Interactions reference](https://subzeroid.github.io/instagrapi/usage-guide/interactions.html)\n* [Best Practices](https://subzeroid.github.io/instagrapi/usage-guide/best-practices.html) for sessions, proxies, and anti-abuse handling\n* [Handle Exceptions](https://subzeroid.github.io/instagrapi/usage-guide/handle_exception.html) for centralizing `429`, challenge, and relogin logic\n* [GitHub Discussions](https://github.com/subzeroid/instagrapi/discussions)\n* Support chat in Telegram: [aiograpi_support](https://t.me/aiograpi_support) — the previous `@instagrapi` group was restricted by Meta and is no longer maintained\n\nFor other languages, consider [instagrapi-rest](https://github.com/subzeroid/instagrapi-rest). For async Python, see [aiograpi](https://github.com/subzeroid/aiograpi).\n\n## Tutorials\n\nHands-on guides for real instagrapi work — login flows, sessions, proxies, scraping, posting, error handling — live at [instagrapi.com/guides](https://instagrapi.com/guides/):\n\n* [Instagram Private API in Python](https://instagrapi.com/guides/instagram-private-api-python/) — pillar walkthrough: login, sessions, fetching, posting\n* [2FA and `challenge_required`](https://instagrapi.com/guides/instagrapi-2fa-challenge/)\n* [Session persistence: file, Redis, and Postgres patterns](https://instagrapi.com/guides/instagrapi-session-persistence/)\n* [Configuring proxies (HTTP, SOCKS5, residential)](https://instagrapi.com/guides/instagrapi-proxy-setup/)\n* [Instagram scraper in Python: a working setup](https://instagrapi.com/guides/instagram-scraper-python/)\n* [Upload a photo from Python](https://instagrapi.com/guides/instagrapi-upload-photo-python/)\n* [Download Instagram stories](https://instagrapi.com/guides/instagrapi-download-stories-python/)\n* [Common errors reference](https://instagrapi.com/guides/errors/) — `bad_password`, `challenge_required`, `login_required`, `please_wait_a_few_minutes`, `feedback_required`, `proxy_address_is_blocked`\n* [`BadPassword`: correct password rejected by Instagram](https://instagrapi.com/guides/errors/bad-password/) — proxy/IP/device/session trust troubleshooting\n* [Framework integrations](https://instagrapi.com/guides/integrations/) — Django, FastAPI, Celery, Docker, AWS Lambda\n\nComparing instagrapi to other tools:\n\n* [instagrapi vs Instaloader](https://instagrapi.com/compare/instaloader/) — download-only vs authenticated automation\n* [instagrapi vs aiograpi](https://instagrapi.com/guides/instagrapi-vs-aiograpi/) — sync or async\n* [Instagram API libraries by language](https://instagrapi.com/guides/instagram-api-libraries-by-language/) — what's actually maintained in 2026\n\n\n\u003cdetails\u003e\n    \u003csummary\u003eAdditional example\u003c/summary\u003e\n\n```python\nfrom instagrapi import Client\nfrom instagrapi.types import StoryMention, StoryMedia, StoryLink, StoryHashtag\n\ncl = Client()\ncl.login(USERNAME, PASSWORD, verification_code=\"\u003c2FA CODE HERE\u003e\")\n\nmedia_pk = cl.media_pk_from_url('https://www.instagram.com/p/CGgDsi7JQdS/')\nmedia_path = cl.video_download(media_pk)\nsubzeroid = cl.user_info_by_username('subzeroid')\nhashtag = cl.hashtag_info('dhbastards')\n\ncl.video_upload_to_story(\n    media_path,\n    \"Credits @subzeroid\",\n    mentions=[StoryMention(user=subzeroid, x=0.49892962, y=0.703125, width=0.8333333333333334, height=0.125)],\n    links=[StoryLink(webUri='https://github.com/subzeroid/instagrapi')],\n    hashtags=[StoryHashtag(hashtag=hashtag, x=0.23, y=0.32, width=0.5, height=0.22)],\n    medias=[StoryMedia(media_pk=media_pk, x=0.5, y=0.5, width=0.6, height=0.8)]\n)\n```\n\u003c/details\u003e\n\n## Related Projects\n\nIf you need async Python, use [aiograpi](https://github.com/subzeroid/aiograpi).\n\nFor other languages, see [instagrapi-rest](https://github.com/subzeroid/instagrapi-rest).\nFor hosted production Instagram API infrastructure, see [HikerAPI](https://hikerapi.com/).\n\nRelated services:\n\n* [Cloqly](https://cloqly.com/register?ref=58dbf70f) for premium rotating proxies and stable automation traffic\n* [DataLikers](https://datalikers.com/p/S9Lv5vBy) for Instagram MCP, Cache API, and datasets\n* [LamaTok](https://lamatok.com/p/B9ScEYIQ) for TikTok API access, automation, and data workflows\n* [InstaSurfBot](https://t.me/InstaSurfBot) for downloading Instagram media in Telegram\n* [OSINTagramBot](https://t.me/OSINTagramBot) for Instagram OSINT in Telegram\n\n### [HikerAPI Affiliate Program](https://hikerapi.com/help/affiliate)\n\nRefer users to HikerAPI and earn a percentage of their API spending:\n\n| Plan | Commission |\n|------|------------|\n| Start trial plan ($0.02/req) | **50%** |\n| Standard ($0.001/req) | **25%** |\n| Business ($0.00069/req) | **15%** |\n| Ultra ($0.0006/req) | **10%** |\n\n**Extras:** 2-level referral system, no caps, lifetime attribution\n\n**Payouts:** USDT / USDC (TRC-20 or ERC-20), minimum 20 USDT, request anytime from the dashboard\n\n## Contributing\n\n[![List of contributors](https://opencollective.com/instagrapi/contributors.svg?width=890\u0026button=0)](https://github.com/subzeroid/instagrapi/graphs/contributors)\n\nFor local setup, tests, linting, and pull request expectations, see [CONTRIBUTING.md](CONTRIBUTING.md) and the [development guide](https://subzeroid.github.io/instagrapi/development-guide.html).\n\nMaintainer release commands:\n\n```bash\ngit tag -a X.Y.Z -m \"Release X.Y.Z\"\ngit push origin X.Y.Z\ngit push codeberg X.Y.Z\n```\n\nThe tag-based `publish.yml` workflow publishes to PyPI via trusted publishing and creates the GitHub release.\n\n## License\n\n`instagrapi` is distributed under the [MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsubzeroid%2Finstagrapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsubzeroid%2Finstagrapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsubzeroid%2Finstagrapi/lists"}