instagram-private-api is a Node.js wrapper for the unofficial Instagram private API, providing programmatic access to various Instagram functionalities typically found in the official mobile applications. The current stable public version is 1.46.1. While it offers extensive features for interacting with Instagram, development for future major versions (e.g., v3.x.x) has transitioned to a private, paid monorepository, shifting active feature development away from this public npm package. This means the public package is primarily in a maintenance state, receiving minimal updates for new features. Key differentiators include its ability to mimic actual device behavior and handle session state, crucial for managing unofficial API interactions.
npm install instagram-private-apiVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to initialize the Instagram API client, log in using environment variables, handle crucial session state persistence (saving/loading cookies and device info to a file), and fetch basic user data from your own and a public profile.
Users requiring new features or active development beyond critical fixes for v1.x will need to contact the maintainer for access to the private repository, or consider alternative solutions.
Implement robust error handling, use proxies, rotate user-agents, and manage session state carefully. Be prepared for frequent updates or changes to your implementation if Instagram alters its internal API. Always use a dedicated test account for development and avoid using personal accounts for automation.
Explicitly install `re2` alongside `instagram-private-api` by running `npm install re2`. This is critical for security and stability.
Use CommonJS `require` syntax: `const { IgApiClient } = require('instagram-private-api');`. Alternatively, configure your project for transpilation (e.g., with Babel or TypeScript targeting CommonJS) or ensure your `package.json` specifies `"type": "module"` for ES module support on newer Node.js versions.Always call `ig.state.generateDevice(process.env.IG_USERNAME ?? '');` with a consistent seed and `await ig.simulate.preLoginFlow();` before logging in. Implement robust session state persistence by serializing and deserializing `ig.state` to disk. You may need to catch `IgCheckpointError` and `IgLoginTwoFactorRequiredError` to implement custom challenge resolution logic.
Change your import statements to CommonJS `require`: `const { IgApiClient } = require('instagram-private-api');`. If using TypeScript, ensure your `tsconfig.json`'s `module` option is set to `CommonJS` or correctly configured for ESNext output with appropriate runtime support.Ensure `ig.state.generateDevice()` is called with a consistent seed and `ig.simulate.preLoginFlow()` is run before login. Crucially, implement session state persistence by saving and loading `ig.state.serialize()` to avoid repeated challenges. You will likely need to catch `IgCheckpointError` and implement a challenge resolver workflow.
Wait for a period (e.g., 10-30 minutes, sometimes longer) before retrying. Consider using proxies (`ig.state.proxyUrl`) and rotating them. Avoid rapid, repetitive actions immediately after login. Ensure `generateDevice` and `preLoginFlow` are correctly used, and ensure login credentials are accurate.
Double-check the username for correctness. Verify that the account is public (if attempting public searches) or that the credentials are for a valid, active account (if attempting login).