instagram4j: a Java client for Instagram's private API, split into mobile and web

A rewrite of a legacy library, split by which endpoints you talk to

instagram4j-v3 is described as an object-oriented rewrite of instagram4j-legacy, because the older library is too old and is no longer maintained. The rewrite grew out of a collaboration: a special thanks goes to ErrorxCode, the creator of JxInsta, which was originally developed as a modern continuation of the library during a period of inactivity, and whose mobile endpoint discovery and architecture improvements were integrated directly into the core of instagram4j. The structure that results is a two artifact library, and the choice between them is the first decision a user makes. There is a `mobile` module and a `web` module, each published separately, and the README says the difference is which API you want to use, with the web module carrying a different login flow. The repository itself reflects the split, with `mobile/` and `web/` directories at the top level alongside `build.gradle`, `settings.gradle`, a Gradle wrapper and `jitpack.yml`, which is the configuration that tells JitPack how to build the artifacts. The default branch is `v3`, so the rewrite is the mainline, while the previous 2.x line stopped at 2.0.7 in January 2022.

Adding it: JitPack, Gradle or Maven

Installation goes through JitPack, which builds the GitHub repository into a Maven artifact, so there is no release to download. The Gradle route asks you to add the JitPack repository to your build file, with a repositories block that includes `mavenCentral()` and the JitPack URL, and then to declare the dependency, choosing between the mobile and the web artifact:

	dependencies {
	        implementation 'com.github.instagram4j.instagram4j:mobile:3.0'   // If you want to use mobile API
          implementation 'com.github.instagram4j.instagram4j:web:3.0'   // If you want to use web API
	}

The Maven route is the mirror image, with the repository declared in the pom and then either a `mobile` or a `web` dependency with a groupId of `com.github.instagram4j.instagram4j` and a version of `3.0`.

What the library actually exposes

The feature list is long and reads like a checklist of Instagram's user facing surface, which is exactly the point of a private API client. Direct messaging is supported for sending, fetching and deleting messages, with a realtime direct messages listener marked as coming soon, and login using cache and saving sessions is supported so that a program can start without a fresh password entry. Content operations include posting pictures, adding photo stories, following and unfollowing, liking and commenting on a post, and fetching feeds and user posts. Scraping is a first class activity rather than an accident: scraping followings and followers, getting profile data, scraping the comments of a post, and fetching reels, stories and highlight. There is also downloading of posts and profile pictures. Two features are explicitly unfinished, accepting or ignoring a follow request, which is marked as coming soon, alongside the realtime listener, and that is worth knowing before you plan a project around a follow request workflow. The README also points at a User guide in the project wiki for details, and the design goal stated in the title block is to do things that you cannot do with the official API.

Authentication: password, cookies, bearer tokens, and a webview on Android

The FAQ in the README answers the question that matters first, which is whether the library needs any tokens or keys. The answer is no, and all you need is the username and password of the account, and you can also log in using cookies and bearer tokens. The three line example shows the shape of the API, constructing the client with a username and a password, fetching a profile and acting on it:

Instagram4j insta = new Instagram4j("username", "password");  
var profile = insta.getProfile("username");
profile.follow();
System.out.print("User Bio : " + profile.bio);

For mobile and desktop, session caching means the program can reuse an authenticated session rather than logging in each run. On Android, the README says you can use a webview to log in, but only for the web module, and that all you need to do is extract the crsf and session id from the cookie after login. The library also answers that you can download stories or posts with it, and to do so without logging in at all. That last answer is a good summary of what this project is: an unauthenticated read path and an authenticated write path over endpoints that Instagram did not intend to be called directly.

The terms of service question the README cannot answer for you

The Acknowledgements section of the README is the most important part of the document for anyone considering production use, and it is a list of links rather than a disclaimer. It points at a breakdown of Instagram's usage limits, a page on Instagram's daily limits, the developer API policies, and a document about Instagram checkpoints and challenges. The FAQ makes the position explicit: yes, you can use the library to make bots, but Instagram does not allow bots with their official graph APIs, and although this is not the official API you should follow the usage limits to prevent detection. The last clause is the one to sit with, because it frames the library as a tool whose normal operation is near a platform boundary. Practically, that means a reverse engineered endpoint can change, that an account used this way can be challenged or checkpointed, and that the account holder, not the library, carries the consequences. None of this is a reason to refuse to look at the code, and the project is a well known piece of Java tooling, but it is a reason to keep it out of anything customer facing unless you have a clear answer for whoever owns the risk.

Maintenance, governance and the shape of the repository

The version history explains the project's rhythm. Version 2.0.7 was released in January 2022 and 2.0.6 in September 2021, then nothing on that line, while version 3.0, described as a complete rewrite, was released on 2026-04-16, and the last push was on 2026-08-17. So the 3.x line is young, the 2.x line is effectively frozen, and the README's advice for anyone who still wants the older library, which has quite a few more features as of now, is to look at EasyInsta, described as an easy to use instagram4j wrapper. The project is Apache-2.0 licensed with a LICENSE file at the root and a `checkpoints.md` document in the tree. The governance is lightweight and personal: there is a CONTRIBUTING guide and a code of conduct, support is offered through Ko-fi, through an Instagram account and through an email address, and the author asks for a star rather than describing a governance model. The repository also has GitHub Actions workflows in `.github/`, and a Gradle wrapper, so a contributor is expected to build with Gradle rather than with an IDE specific setup.

Editorial conclusion

Adopt instagram4j if you are building a personal or internal tool that needs Instagram data the official API will not give you, and you can live with the terms of service risk that the library's own README points at. Do not adopt it for a product that depends on a stable, supported contract, because the endpoints are reverse engineered and can change without notice, and do not adopt it if automated account behaviour is something you have to explain to a compliance team. Before you build, decide between the mobile and the web module, since they are separate artifacts with different login flows, and read the acknowledgement section of the README, which links the usage limits, the daily limits, the developer policies and a document about Instagram checkpoints. The licence is Apache-2.0, version 3.0 was released on 2026-04-16, and the last push was on 2026-08-17.

Frequently asked questions

Official sources

1. instagram4j/instagram4j on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases