Start with 100 free credits. No card needed. Get an API key

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.

Shell
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".

Shell
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

ExceptionMessage (or the start of it)Fix
LoginRequiredExceptionRedirected to login page. Use --login or --load-cookies.Login required
BadCredentialsExceptionLogin error: Wrong password.Bad credentials
TwoFactorAuthRequiredExceptionLogin error: two-factor authentication required.Bad credentials
TooManyRequestsException429 Too Many RequestsToo many requests
ConnectionException401 Unauthorized ... Please wait a few minutes before you try again.Too many requests
PrivateProfileNotFollowedExceptionprivate but not followed.Private profile
ProfileNotExistsExceptionProfile NAME does not exist.Profile not found
AbortDownloadExceptioncheckpoint_required, challenge_required or feedback_requiredCheckpoint
LoginExceptionLogin: Checkpoint required. Point your browser to ...Checkpoint
QueryReturnedForbiddenException403 Forbidden on a file downloadThe signed file link was refused: load the post again
QueryReturnedNotFoundException404 Not FoundThe 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:

Shell
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 forSocialScrape 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 pageGET /v1/instagram/post/comments
L.get_highlights()GET /v1/instagram/profile/highlights
L.get_hashtag_posts()GET /v1/instagram/search/hashtag
Followers, followees, current storiesNot 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.

Get started

Start pulling social data.

100 free credits. No card needed.