instaloader not working
Most breakages come down to the session, the pace, or a change on Instagram's side. Find your exception below; each row links to its cause and fix.
Three checks first
Instagram reshapes the pages and queries instaloader reads, and the fixes arrive as new releases. When a command that worked last month fails today, go through these before reading the traceback closely.
1. Update. The docs list 4.16, released on 26 October 2026, as the current version.
python3 -m pip install -U instaloader instaloader --version
2. Keep one saved session. Log in once with --login and let later runs reuse the session file it writes. The troubleshooting page recommends keeping that file and says session files "usually do not expire".
instaloader --login YOUR_USERNAME profile_name
3. Run a single instance. When Instagram answers 429, instaloader's own message asks you not to run several instances in parallel or in short sequence, and not to use any Instagram app while it runs.
These pages are written against instaloader 4.16 and quote its source.
Find your exception
| Exception | Message (or the start of it) | Fix |
|---|---|---|
LoginRequiredException | Redirected to login page. Use --login or --load-cookies. | Login required |
BadCredentialsException | Login error: Wrong password. | Bad credentials |
TwoFactorAuthRequiredException | Login error: two-factor authentication required. | Bad credentials |
TooManyRequestsException | 429 Too Many Requests | Too many requests |
ConnectionException | 401 Unauthorized ... Please wait a few minutes before you try again. | Too many requests |
PrivateProfileNotFollowedException | private but not followed. | Private profile |
ProfileNotExistsException | Profile NAME does not exist. | Profile not found |
AbortDownloadException | checkpoint_required, challenge_required or feedback_required | Checkpoint |
LoginException | Login: Checkpoint required. Point your browser to ... | Checkpoint |
QueryReturnedForbiddenException | 403 Forbidden on a file download | The signed file link was refused: load the post again |
QueryReturnedNotFoundException | 404 Not Found | The item is gone, or the query changed: update |
Which ones stop the whole run
Every exception in the table but one derives from InstaloaderException. The command line catches those per target, prints them, carries on with the next profile, and repeats the errors at the end.
AbortDownloadException is the one that ends everything. It does not derive from InstaloaderException, so except InstaloaderException lets it through, and the command line prints Download aborted: and exits. instaloader raises it on purpose when Instagram asks for a checkpoint, so that no more requests go out. The --abort-on option makes chosen status codes behave the same way and skip the retries:
instaloader --abort-on=400,429 profile_name
For a scheduled job that is often the better trade: a run that fails in seconds is easier to handle than one asleep for many minutes.
The Instagram jobs that do not need instaloader
A lot of instaloader code only reads: a profile's numbers, its latest posts, a post's comments. For those, SocialScrape is one HTTP request with no session file, and each maps onto an instaloader call:
| You use instaloader for | SocialScrape endpoint |
|---|---|
Profile.from_username() | GET /v1/instagram/profile |
Profile.from_id() | GET /v1/instagram/basic-profile |
profile.get_posts() | GET /v1/instagram/profile/posts |
profile.get_reels() | GET /v1/instagram/profile/reels |
Post.from_shortcode() | GET /v1/instagram/post |
post.get_comments(), first page | GET /v1/instagram/post/comments |
L.get_highlights() | GET /v1/instagram/profile/highlights |
L.get_hashtag_posts() | GET /v1/instagram/search/hashtag |
| Followers, followees, current stories | Not offered |
A profile, a post or one page of a list is 1 credit, and a request that fails is free. New accounts start with 100 credits, no card.
Questions, answered.
Common questions
Is instaloader still maintained?
Yes, at the time of writing. Version 4.16 came out on 26 October 2026.
Does instaloader need an Instagram account?
Not for every call. Comments, likes, followers, followees, saved posts and the iPhone endpoints raise LoginRequiredException without a session, and a private profile needs a session that follows it.
Why does it fail on my server but not on my laptop?
The address. The troubleshooting page warns that cloud, VPN and public proxy services "might be subject to significantly stricter limits" than a home connection.
Should I apply a patch from a GitHub issue?
Several 401 issues from 2025 carry patches written by users, such as dropping the empty sessionid cookie. Commenters say they work "sometimes, but not always", and no maintainer has confirmed one, so update first.
Start pulling social data.
100 free credits. No card needed.