---
id: instagrapi
version: "2.18.14"
license: MIT
license_treatment: permissive
maintenance: active
---

# instagrapi — Fast and effective Instagram Private API wrapper

License: permissive · Maintenance: active · Downloads: 2.0M/mo

## What it is and what it does

instagrapi is an unofficial Python wrapper around Instagram's private mobile API and public web endpoints. It handles authentication, session persistence, challenge flows, and rate-limit recovery to support automation tasks like downloading user posts, searching locations, sending direct messages, uploading stories and reels, and reading insights. The library combines both API flows to maximize coverage of Instagram's features.

The package is designed for testing, research, and controlled internal automation rather than production account management. It depends on requests for HTTP, PySocks for proxy support, pydantic for data validation, Pillow for image handling, and pycryptodomex for cryptographic operations. Optional extras add TLS fingerprint impersonation (curl) and video composition (MoviePy 2.2.1 + ffmpeg). The maintainers explicitly recommend official Instagram APIs for business workflows and hosted providers like HikerAPI for production private API infrastructure.

Use it for:

- Download another user's posts and media in bulk for archival or analysis.
- Automate direct message sending and reading for internal team workflows or testing.
- Search and retrieve location metadata and posts by geographic area.
- Upload stories, reels, and feed posts programmatically for content scheduling.
- Monitor account insights and engagement metrics via the private API.
- Receive real-time direct message notifications over MQTT for reactive automation.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Unofficial Instagram API wrapper that automates private mobile and public web flows for users, media, stories, direct messages, and uploads with session persistence and challenge handling.

Yes, if your use case is internal testing, research, or controlled automation on accounts you own or manage. No, if you need production-grade stability or are building customer-facing features—use official Instagram APIs instead. The library is actively maintained and has no known vulnerabilities, but private API automation is inherently fragile because Instagram's account trust, device state, and rate limits change independently of the library. For production infrastructure, consider a hosted provider.

## Install

pip install instagrapi
uv add instagrapi
poetry add instagrapi

## Installing instagrapi

Before you install: Low friction install with five runtime dependencies (requests, PySocks, pydantic, Pillow, pycryptodomex). Active maintenance with release 2 days ago. Requires Python 3.10+; Python 3.9 support was dropped in version 2.5.0 due to upstream security patch constraints.

License in practice: MIT license permits commercial and private use with minimal restrictions—suitable for internal automation and testing workflows.

Quickstart:

pip install instagrapi

from instagrapi import Client

cl = Client()
cl.login(USERNAME, PASSWORD)
user_id = cl.user_id_from_username(USERNAME)
medias = cl.user_medias(user_id, 20)

Requires Python 3.10 or later. Private API automation is fragile in production—account trust, proxies, device state, challenges, and rate limits can change independently of the library.

Verify before relying:

- Whether optional video dependencies (MoviePy 2.2.1, ffmpeg) are required for your specific use case or only for video/story uploads.
- Whether curl-backed TLS impersonation (instagrapi[curl] extra) is necessary for your target endpoints or if standard requests suffices.
- Stability and rate-limit behavior of the private mobile API flows in your deployment environment.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 2.0M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

instagram api wrapper python, instagram automation library, instagram private api client, instagram scraper downloader, instagram bot framework, instagram direct messages api, instagram reels uploader, instagram-api, web-scraping, automation

[View on SkillFed](https://skillfed.io/packages/instagrapi) · [View on PyPI](https://pypi.org/project/instagrapi/)