Instaloader (Main Class)

class Instaloader(sleep=True, quiet=False, user_agent=None, dirname_pattern=None, filename_pattern=None, download_pictures=True, download_videos=True, download_video_thumbnails=True, download_geotags=False, download_comments=False, save_metadata=True, compress_json=True, post_metadata_txt_pattern=None, storyitem_metadata_txt_pattern=None, max_connection_attempts=3, request_timeout=300.0, rate_controller=None, resume_prefix='iterator', check_resume_bbd=True, slide=None, fatal_status_codes=None, iphone_support=True, title_pattern=None, sanitize_paths=False)

Instaloader Class.

Parameters

• quiet (bool) – --quiet

• user_agent (Optional[str]) – --user-agent

• dirname_pattern (Optional[str]) – --dirname-pattern, default is {target}

• filename_pattern (Optional[str]) – --filename-pattern, default is {date_utc}_UTC

• title_pattern (Optional[str]) – --title-pattern, default is {date_utc}_UTC_{typename} if dirname_pattern contains {target} or {profile}, {target}_{date_utc}_UTC_{typename} otherwise.

• download_pictures – not --no-pictures

• download_videos (bool) – not --no-videos

• download_video_thumbnails (bool) – not --no-video-thumbnails

• download_geotags (bool) – --geotags

• download_comments (bool) – --comments

• save_metadata (bool) – not --no-metadata-json

• compress_json (bool) – not --no-compress-json

• post_metadata_txt_pattern (Optional[str]) – --post-metadata-txt, default is {caption}. Set to empty string to avoid creation of post metadata txt file.

• storyitem_metadata_txt_pattern (Optional[str]) – --storyitem-metadata-txt, default is empty (=none)

• max_connection_attempts (int) – --max-connection-attempts

• request_timeout (float) – --request-timeout, set per-request timeout (seconds)

• rate_controller (Optional[Callable[[InstaloaderContext], RateController]]) – Generator for a RateController to override rate controlling behavior

• resume_prefix (Optional[str]) – --resume-prefix, or None for --no-resume.

• check_resume_bbd (bool) – Whether to check the date of expiry of resume files and reject them if expired.

• slide (Optional[str]) – --slide

• fatal_status_codes (Optional[List[int]]) – --abort-on

• iphone_support (bool) – not --no-iphone

• sanitize_paths (bool) – --sanitize-paths

context

The associated InstaloaderContext with low-level communication functions and logging.

anonymous_copy()

Yield an anonymous, otherwise equally-configured copy of an Instaloader instance; Then copy its error log.

close()

Close associated session objects and repeat error log.

download_pic(filename, url, mtime, filename_suffix=None, _attempt=1)

Downloads and saves picture with given url under given directory with given timestamp. Returns true, if file was actually downloaded, i.e. updated.

Return type

bool

save_metadata_json(filename, structure)

Saves metadata JSON file of a structure.

Return type

None

update_comments(filename, post)

Return type

None

save_caption(filename, mtime, caption)

Updates picture caption / Post metadata info

Return type

None

save_location(filename, location, mtime)

Save post location name and Google Maps link.

Return type

None

format_filename_within_target_path(target, owner_profile, identifier, name_suffix, extension)

Returns a filename within the target path.

New in version 4.5.

download_title_pic(url, target, name_suffix, owner_profile, _attempt=1)

Downloads and saves a picture that does not have an association with a Post or StoryItem, such as a Profile picture or a Highlight cover picture. Modification time is taken from the HTTP response headers.

New in version 4.3.

Return type

None

download_profilepic_if_new(profile, latest_stamps)

Downloads and saves profile pic if it has not been downloaded before.

Parameters

latest_stamps (Optional[LatestStamps]) – Database with the last downloaded data. If not present, the profile pic is downloaded unless it already exists

New in version 4.8.

Return type

None

download_profilepic(profile)

Downloads and saves profile pic.

Return type

None

download_highlight_cover(highlight, target)

Downloads and saves Highlight cover picture.

New in version 4.3.

Return type

None

download_hashtag_profilepic(hashtag)

Downloads and saves the profile picture of a Hashtag.

New in version 4.4.

Return type

None

save_session()

Saves internally stored requests.Session object to dict.

Raises

LoginRequiredException – If called without being logged in.

New in version 4.10.

Return type

dict

load_session(username, session_data)

Internally stores requests.Session object from dict.

New in version 4.10.

Return type

None

save_session_to_file(filename=None)

Saves internally stored requests.Session object.

Parameters

filename (Optional[str]) – Filename, or None to use default filename.

Raises

LoginRequiredException – If called without being logged in.

Return type

None

load_session_from_file(username, filename=None)

Internally stores requests.Session object loaded from file.

If filename is None, the file with the default session path is loaded.

Raises

FileNotFoundError – If the file does not exist.

Return type

None

test_login()

Returns the Instagram username to which given requests.Session object belongs, or None.

Return type

Optional[str]

login(user, passwd)

Log in to instagram with given username and password and internally store session object.

Raises

• InvalidArgumentException – If the provided username does not exist.

• BadCredentialsException – If the provided password is wrong.

• ConnectionException – If connection to Instagram failed.

• TwoFactorAuthRequiredException – First step of 2FA login done, now call Instaloader.two_factor_login().

Return type

None

two_factor_login(two_factor_code)

Second step of login if 2FA is enabled. Not meant to be used directly, use Instaloader.two_factor_login().

Raises

• InvalidArgumentException – No two-factor authentication pending.

• BadCredentialsException – 2FA verification code invalid.

New in version 4.2.

Return type

None

format_filename(item, target=None)

Format filename of a Post or StoryItem according to filename-pattern parameter.

New in version 4.1.

download_post(post, target)

Download everything associated with one instagram post node, i.e. picture, caption and video.

Parameters

• post (Post) – Post to download.

• target (Union[str, Path]) – Target name, i.e. profile name, #hashtag, :feed; for filename.

Return type

bool

Returns

True if something was downloaded, False otherwise, i.e. file was already there

get_stories(userids=None)

Get available stories from followees or all stories of users whose ID are given. Does not mark stories as seen. To use this, one needs to be logged in

Parameters

userids (Optional[List[int]]) – List of user IDs to be processed in terms of downloading their stories, or None.

Raises

LoginRequiredException – If called without being logged in.

Return type

Iterator[Story]

download_stories(userids=None, fast_update=False, filename_target=':stories', storyitem_filter=None, latest_stamps=None)

Download available stories from user followees or all stories of users whose ID are given. Does not mark stories as seen. To use this, one needs to be logged in

Parameters

• userids (Optional[List[Union[int, Profile]]]) – List of user IDs or Profiles to be processed in terms of downloading their stories

• fast_update (bool) – If true, abort when first already-downloaded picture is encountered

• filename_target (Optional[str]) – Replacement for {target} in dirname_pattern and filename_pattern or None if profile name should be used instead

• storyitem_filter (Optional[Callable[[StoryItem], bool]]) – function(storyitem), which returns True if given StoryItem should be downloaded

• latest_stamps (Optional[LatestStamps]) – Database with the last times each user was scraped

Raises

LoginRequiredException – If called without being logged in.

Changed in version 4.8: Add latest_stamps parameter.

Return type

None

download_storyitem(item, target)

Download one user story.

Parameters

• item (StoryItem) – Story item, as in story[‘items’] for story in get_stories()

• target (Union[str, Path]) – Replacement for {target} in dirname_pattern and filename_pattern

Return type

bool

Returns

True if something was downloaded, False otherwise, i.e. file was already there

get_highlights(user)

Get all highlights from a user. To use this, one needs to be logged in.

New in version 4.1.

Parameters

user (Union[int, Profile]) – ID or Profile of the user whose highlights should get fetched.

Raises

LoginRequiredException – If called without being logged in.

Return type

Iterator[Highlight]

download_highlights(user, fast_update=False, filename_target=None, storyitem_filter=None)

Download available highlights from a user whose ID is given. To use this, one needs to be logged in.

New in version 4.1.

Changed in version 4.3: Also downloads and saves the Highlight’s cover pictures.

Parameters

• user (Union[int, Profile]) – ID or Profile of the user whose highlights should get downloaded.

• fast_update (bool) – If true, abort when first already-downloaded picture is encountered

• filename_target (Optional[str]) – Replacement for {target} in dirname_pattern and filename_pattern or None if profile name and the highlights’ titles should be used instead

• storyitem_filter (Optional[Callable[[StoryItem], bool]]) – function(storyitem), which returns True if given StoryItem should be downloaded

Raises

LoginRequiredException – If called without being logged in.

Return type

None

posts_download_loop(posts, target, fast_update=False, post_filter=None, max_count=None, total_count=None, owner_profile=None, takewhile=None)

Download the Posts returned by given Post Iterator.

New in version 4.4.

Changed in version 4.5: Transparently resume an aborted operation if posts is a NodeIterator.

Changed in version 4.8: Add takewhile parameter.

Parameters

• posts (Iterator[Post]) – Post Iterator to loop through.

• target (Union[str, Path]) – Target name.

• fast_update (bool) – --fast-update.

• post_filter (Optional[Callable[[Post], bool]]) – --post-filter.

• max_count (Optional[int]) – Maximum count of Posts to download (--count).

• total_count (Optional[int]) – Total number of posts returned by given iterator.

• owner_profile (Optional[Profile]) – Associated profile, if any.

• takewhile (Optional[Callable[[Post], bool]]) – Expression evaluated for each post. Once it returns false, downloading stops.

Return type

None

get_feed_posts()

Get Posts of the user’s feed.

Return type

Iterator[Post]

Returns

Iterator over Posts of the user’s feed.

Raises

LoginRequiredException – If called without being logged in.

download_feed_posts(max_count=None, fast_update=False, post_filter=None)

Download pictures from the user’s feed.

Example to download up to the 20 pics the user last liked:

loader = Instaloader()
loader.load_session_from_file('USER')
loader.download_feed_posts(max_count=20, fast_update=True,
                           post_filter=lambda post: post.viewer_has_liked)

Parameters

• max_count (Optional[int]) – Maximum count of pictures to download

• fast_update (bool) – If true, abort when first already-downloaded picture is encountered

• post_filter (Optional[Callable[[Post], bool]]) – function(post), which returns True if given picture should be downloaded

Raises

LoginRequiredException – If called without being logged in.

Return type

None

download_saved_posts(max_count=None, fast_update=False, post_filter=None)

Download user’s saved pictures.

Parameters

• max_count (Optional[int]) – Maximum count of pictures to download

• fast_update (bool) – If true, abort when first already-downloaded picture is encountered

• post_filter (Optional[Callable[[Post], bool]]) – function(post), which returns True if given picture should be downloaded

Raises

LoginRequiredException – If called without being logged in.

Return type

None

get_location_posts(location)

Get Posts which are listed by Instagram for a given Location.

Return type

Iterator[Post]

Returns

Iterator over Posts of a location’s posts

Raises

LoginRequiredException – If called without being logged in.

New in version 4.2.

Changed in version 4.2.9: Require being logged in (as required by Instagram)

download_location(location, max_count=None, post_filter=None, fast_update=False)

Download pictures of one location.

To download the last 30 pictures with location 362629379, do:

loader = Instaloader()
loader.download_location(362629379, max_count=30)

Parameters

• location (str) – Location to download, as Instagram numerical ID

• max_count (Optional[int]) – Maximum count of pictures to download

• post_filter (Optional[Callable[[Post], bool]]) – function(post), which returns True if given picture should be downloaded

• fast_update (bool) – If true, abort when first already-downloaded picture is encountered

Raises

LoginRequiredException – If called without being logged in.

New in version 4.2.

Changed in version 4.2.9: Require being logged in (as required by Instagram)

Return type

None

get_explore_posts()

Get Posts which are worthy of exploring suggested by Instagram.

Returns

Iterator over Posts of the user’s suggested posts.

Return type

NodeIterator[Post]

Raises

LoginRequiredException – If called without being logged in.

get_hashtag_posts(hashtag)

Get Posts associated with a #hashtag.

Deprecated since version 4.4: Use Hashtag.get_posts_resumable().

Return type

Iterator[Post]

download_hashtag(hashtag, max_count=None, post_filter=None, fast_update=False, profile_pic=True, posts=True)

Download pictures of one hashtag.

To download the last 30 pictures with hashtag #cat, do:

loader = Instaloader()
loader.download_hashtag('cat', max_count=30)

Parameters

• hashtag (Union[Hashtag, str]) – Hashtag to download, as instance of Hashtag, or string without leading ‘#’

• max_count (Optional[int]) – Maximum count of pictures to download

• post_filter (Optional[Callable[[Post], bool]]) – function(post), which returns True if given picture should be downloaded

• fast_update (bool) – If true, abort when first already-downloaded picture is encountered

• profile_pic (bool) – not --no-profile-pic.

• posts (bool) – not --no-posts.

Changed in version 4.4: Add parameters profile_pic and posts.

Return type

None

download_tagged(profile, fast_update=False, target=None, post_filter=None, latest_stamps=None)

Download all posts where a profile is tagged.

New in version 4.1.

Changed in version 4.8: Add latest_stamps parameter.

Return type

None

download_igtv(profile, fast_update=False, post_filter=None, latest_stamps=None)

Download IGTV videos of a profile.

New in version 4.3.

Changed in version 4.8: Add latest_stamps parameter.

Return type

None

load_profile_id(profile_name)

Load ID of profile from profile directory.

New in version 4.8.

Return type

Optional[int]

save_profile_id(profile)

Store ID of profile on profile directory.

New in version 4.0.6.

check_profile_id(profile_name, latest_stamps=None)

Consult locally stored ID of profile with given name, check whether ID matches and whether name has changed and return current name of the profile, and store ID of profile.

Parameters

• profile_name (str) – Profile name

• latest_stamps (Optional[LatestStamps]) – Database of downloaded data. If present, IDs are retrieved from it, otherwise from the target directory

Return type

Profile

Returns

Instance of current profile

Changed in version 4.8: Add latest_stamps parameter.

download_profiles(profiles, profile_pic=True, posts=True, tagged=False, igtv=False, highlights=False, stories=False, fast_update=False, post_filter=None, storyitem_filter=None, raise_errors=False, latest_stamps=None)

High-level method to download set of profiles.

Parameters

• profiles (Set[Profile]) – Set of profiles to download.

• profile_pic (bool) – not --no-profile-pic.

• posts (bool) – not --no-posts.

• tagged (bool) – --tagged.

• igtv (bool) – --igtv.

• highlights (bool) – --highlights.

• stories (bool) – --stories.

• fast_update (bool) – --fast-update.

• post_filter (Optional[Callable[[Post], bool]]) – --post-filter.

• storyitem_filter (Optional[Callable[[Post], bool]]) – --post-filter.

• raise_errors (bool) – Whether LoginRequiredException and PrivateProfileNotFollowedException should be raised or catched and printed with InstaloaderContext.error_catcher().

• latest_stamps (Optional[LatestStamps]) – --latest-stamps.

New in version 4.1.

Changed in version 4.3: Add igtv parameter.

Changed in version 4.8: Add latest_stamps parameter.

download_profile(profile_name, profile_pic=True, profile_pic_only=False, fast_update=False, download_stories=False, download_stories_only=False, download_tagged=False, download_tagged_only=False, post_filter=None, storyitem_filter=None)

Download one profile

Deprecated since version 4.1: Use Instaloader.download_profiles().

Return type

None

interactive_login(username)

Logs in and internally stores session, asking user for password interactively.

Raises

• LoginRequiredException – when in quiet mode.

• InvalidArgumentException – If the provided username does not exist.

• ConnectionException – If connection to Instagram failed.

Return type

None

Next Section

Instagram Structures